declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/.declapract.integration.test.ts

@@ -2,7 +2,9 @@ import fs from 'fs/promises';
 import path from 'node:path';
 
 import { executeApply } from 'declapract';
-import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { genTempRepoWithDeclarationsOutside } from '../../utils/genTempRepoWithDeclarationsOutside';
 
 // executeApply is slow (90+ seconds per invocation due to full practice evaluation)
 jest.setTimeout(180_000); // 3 minutes
@@ -16,13 +18,11 @@ jest.setTimeout(180_000); // 3 minutes
  */
 describe('cache practice with ifInstalled', () => {
   given('[case1] repo WITHOUT cache package installed', () => {
-    const tempDir = genTempDir({
+    const tempDir = genTempRepoWithDeclarationsOutside({
       slug: 'cache-not-installed',
       clone: './src/practices/cache/.test/assets/repo-without-cache-package',
-      symlink: [
-        { at: 'declarations', to: './src/.test/assets/cache/declarations' },
-        { at: 'node_modules', to: 'node_modules' },
-      ],
+      declarations: './src/.test/assets/cache/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
     });
 
     // run executeApply before assertions
@@ -49,13 +49,11 @@ describe('cache practice with ifInstalled', () => {
   });
 
   given('[case2] repo WITH outdated cache package', () => {
-    const tempDir = genTempDir({
+    const tempDir = genTempRepoWithDeclarationsOutside({
       slug: 'cache-outdated',
       clone: './src/practices/cache/.test/assets/repo-with-old-cache-package',
-      symlink: [
-        { at: 'declarations', to: './src/.test/assets/cache/declarations' },
-        { at: 'node_modules', to: 'node_modules' },
-      ],
+      declarations: './src/.test/assets/cache/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
     });
 
     // run executeApply before assertions
@@ -78,13 +76,11 @@ describe('cache practice with ifInstalled', () => {
   });
 
   given('[case3] repo WITH valid cache package version', () => {
-    const tempDir = genTempDir({
+    const tempDir = genTempRepoWithDeclarationsOutside({
       slug: 'cache-valid',
       clone: './src/practices/cache/.test/assets/repo-with-valid-cache-package',
-      symlink: [
-        { at: 'declarations', to: './src/.test/assets/cache/declarations' },
-        { at: 'node_modules', to: 'node_modules' },
-      ],
+      declarations: './src/.test/assets/cache/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
     });
 
     // run executeApply before assertions
@@ -105,4 +101,104 @@ describe('cache practice with ifInstalled', () => {
       });
     });
   });
+
+  given('[case4] repo WITH a retired member, a member below its new floor, and retired directory options (#625, #644)', () => {
+    const tempDir = genTempRepoWithDeclarationsOutside({
+      slug: 'cache-retired-member',
+      clone: './src/practices/cache/.test/assets/repo-with-retired-cache-member',
+      declarations: './src/.test/assets/cache/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
+    });
+    const srcPath = 'src/utils/cache/getCacheDirectory.ts';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyAll = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'cache',
+      });
+
+    when('[t0] the cache practice is applied, then applied again', () => {
+      const result = useBeforeAll(async () => {
+        const before = { pkg: await read('package.json'), src: await read(srcPath) };
+        await applyAll();
+        const once = { pkg: await read('package.json'), src: await read(srcPath) };
+        await applyAll();
+        const twice = { pkg: await read('package.json'), src: await read(srcPath) };
+        return { before, once, twice };
+      }, 300_000);
+
+      then('the retired member moves to with-simple-cache, and the family floor reaches with-domain-driven-cache', () => {
+        const pkg = JSON.parse(result.once.pkg);
+        expect(pkg.dependencies['with-simple-caching']).toBeUndefined();
+        expect(pkg.dependencies['with-simple-cache']).toBe('0.17.3');
+        expect(pkg.dependencies['with-domain-driven-cache']).toBe('1.1.5');
+        expect(result.before.pkg).toMatchSnapshot('package.json — before');
+        expect(result.once.pkg).toMatchSnapshot('package.json — after');
+      });
+
+      then('each retired directory option carries a review line that names `directory`', () => {
+        const lines = result.once.src.split('\n');
+        const persistIndex = lines.findIndex((line) =>
+          line.includes('directoryToPersistTo: {'),
+        );
+        const s3Index = lines.findIndex((line) => line.includes('s3: {'));
+        expect(lines[persistIndex - 1]).toContain('// @declapract:review:');
+        expect(lines[s3Index - 1]).toContain('// @declapract:review:');
+        expect(result.once.src).toContain('`directory`');
+        expect(result.before.src).toMatchSnapshot('getCacheDirectory.ts — before');
+        expect(result.once.src).toMatchSnapshot('getCacheDirectory.ts — after');
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(result.twice).toEqual(result.once);
+      });
+    });
+  });
+
+  given('[case5] repo WITH the retired member still imported by src (#625)', () => {
+    const tempDir = genTempRepoWithDeclarationsOutside({
+      slug: 'cache-retired-member-imported',
+      clone: './src/practices/cache/.test/assets/repo-with-retired-cache-member-imported',
+      declarations: './src/.test/assets/cache/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
+    });
+    const srcPath = 'src/logic/getWaveReport.ts';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyAll = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'cache',
+      });
+
+    when('[t0] the cache practice is applied, then applied again', () => {
+      const result = useBeforeAll(async () => {
+        const before = { pkg: await read('package.json'), src: await read(srcPath) };
+        await applyAll();
+        const once = { pkg: await read('package.json'), src: await read(srcPath) };
+        await applyAll();
+        const twice = { pkg: await read('package.json'), src: await read(srcPath) };
+        return { before, once, twice };
+      }, 300_000);
+
+      then('the dep stays, so the import still builds', () => {
+        const pkg = JSON.parse(result.once.pkg);
+        expect(pkg.dependencies['with-simple-caching']).toBe('0.14.4');
+        expect(pkg.dependencies['with-simple-cache']).toBeUndefined();
+      });
+
+      then('the import carries a review line that names with-simple-cache', () => {
+        expect(result.once.src.split('\n')[0]).toContain(
+          '// @declapract:review: with-simple-caching is retired',
+        );
+        expect(result.before.src).toMatchSnapshot('getWaveReport.ts — before');
+        expect(result.once.src).toMatchSnapshot('getWaveReport.ts — after');
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(result.twice).toEqual(result.once);
+      });
+    });
+  });
 });

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/.test/assets/repo-with-retired-cache-member/declapract.use.yml

@@ -0,0 +1,6 @@
+# .note = declarations dir is symlinked by the test (contains declapract.declare.yml + practices/)
+declarations: 'declarations/declapract.declare.yml'
+useCase: typescript-project
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project-retired-cache'

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/.test/assets/repo-with-retired-cache-member/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "test-project-retired-cache",
+  "version": "1.0.0",
+  "dependencies": {
+    "with-domain-driven-cache": "1.0.0",
+    "with-simple-caching": "0.14.4"
+  }
+}

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/.test/assets/repo-with-retired-cache-member/src/utils/cache/getCacheDirectory.ts

@@ -0,0 +1,10 @@
+import { createCache } from 'simple-on-disk-cache';
+
+export const getCacheDirectory = () => ({
+  directoryToPersistTo: {
+    mounted: { path: '/tmp/cache' },
+    s3: { bucket: 'svc-cache', prefix: 'surf' },
+  },
+});
+
+export const cache = createCache(getCacheDirectory());

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/.test/assets/repo-with-retired-cache-member-imported/declapract.use.yml

@@ -0,0 +1,6 @@
+# .note = declarations dir is symlinked by the test (contains declapract.declare.yml + practices/)
+declarations: 'declarations/declapract.declare.yml'
+useCase: typescript-project
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project-retired-cache-imported'

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/.test/assets/repo-with-retired-cache-member-imported/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "test-project-retired-cache-imported",
+  "version": "1.0.0",
+  "dependencies": {
+    "with-simple-caching": "0.14.4"
+  }
+}

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/.test/assets/repo-with-retired-cache-member-imported/src/logic/getWaveReport.ts

@@ -0,0 +1,5 @@
+import { withSimpleCaching } from 'with-simple-caching';
+
+export const getWaveReport = withSimpleCaching(async () => 'swell', {
+  cache: new Map(),
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,73 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`cache practice with ifInstalled given: [case4] repo WITH a retired member, a member below its new floor, and retired directory options (#625, #644) when: [t0] the cache practice is applied, then applied again then: each retired directory option carries a review line that names \`directory\`: getCacheDirectory.ts — after 1`] = `
+"import { createCache } from 'simple-on-disk-cache';
+
+export const getCacheDirectory = () => ({
+  // @declapract:review: with-simple-cache 0.17.3 retired \`s3\` and \`directoryToPersistTo\` — pass \`directory\` in their place, and \`await\` each cache \`get()\`, which now returns a Promise. then delete this marker
+  directoryToPersistTo: {
+    mounted: { path: '/tmp/cache' },
+    // @declapract:review: with-simple-cache 0.17.3 retired \`s3\` and \`directoryToPersistTo\` — pass \`directory\` in their place, and \`await\` each cache \`get()\`, which now returns a Promise. then delete this marker
+    s3: { bucket: 'svc-cache', prefix: 'surf' },
+  },
+});
+
+export const cache = createCache(getCacheDirectory());
+"
+`;
+
+exports[`cache practice with ifInstalled given: [case4] repo WITH a retired member, a member below its new floor, and retired directory options (#625, #644) when: [t0] the cache practice is applied, then applied again then: each retired directory option carries a review line that names \`directory\`: getCacheDirectory.ts — before 1`] = `
+"import { createCache } from 'simple-on-disk-cache';
+
+export const getCacheDirectory = () => ({
+  directoryToPersistTo: {
+    mounted: { path: '/tmp/cache' },
+    s3: { bucket: 'svc-cache', prefix: 'surf' },
+  },
+});
+
+export const cache = createCache(getCacheDirectory());
+"
+`;
+
+exports[`cache practice with ifInstalled given: [case4] repo WITH a retired member, a member below its new floor, and retired directory options (#625, #644) when: [t0] the cache practice is applied, then applied again then: the retired member moves to with-simple-cache, and the family floor reaches with-domain-driven-cache: package.json — after 1`] = `
+"{
+  "name": "test-project-retired-cache",
+  "version": "1.0.0",
+  "dependencies": {
+    "with-domain-driven-cache": "1.1.5",
+    "with-simple-cache": "0.17.3"
+  }
+}
+"
+`;
+
+exports[`cache practice with ifInstalled given: [case4] repo WITH a retired member, a member below its new floor, and retired directory options (#625, #644) when: [t0] the cache practice is applied, then applied again then: the retired member moves to with-simple-cache, and the family floor reaches with-domain-driven-cache: package.json — before 1`] = `
+"{
+  "name": "test-project-retired-cache",
+  "version": "1.0.0",
+  "dependencies": {
+    "with-domain-driven-cache": "1.0.0",
+    "with-simple-caching": "0.14.4"
+  }
+}"
+`;
+
+exports[`cache practice with ifInstalled given: [case5] repo WITH the retired member still imported by src (#625) when: [t0] the cache practice is applied, then applied again then: the import carries a review line that names with-simple-cache: getWaveReport.ts — after 1`] = `
+"// @declapract:review: with-simple-caching is retired — import from with-simple-cache (>=0.17.3) in its place: its cache \`get()\` is async, and its on-disk \`directory\` option replaces \`s3\` / \`directoryToPersistTo\`. then delete this marker
+import { withSimpleCaching } from 'with-simple-caching';
+
+export const getWaveReport = withSimpleCaching(async () => 'swell', {
+  cache: new Map(),
+});
+"
+`;
+
+exports[`cache practice with ifInstalled given: [case5] repo WITH the retired member still imported by src (#625) when: [t0] the cache practice is applied, then applied again then: the import carries a review line that names with-simple-cache: getWaveReport.ts — before 1`] = `
+"import { withSimpleCaching } from 'with-simple-caching';
+
+export const getWaveReport = withSimpleCaching(async () => 'swell', {
+  cache: new Map(),
+});
+"
+`;

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/bad-practices/cache-directory-options/.declapract.readme.md

@@ -0,0 +1,5 @@
+a cache directory option retired at with-simple-cache `0.17.3`: `directoryToPersistTo` or `s3`.
+
+`directory` replaces both, and each cache `get()` now returns a Promise. the right `directory` shape
+depends on where the repo persists its cache, so the fix stamps a `// @declapract:review:` line above
+each retired option and rewrites no code. the check stays red until a human moves the option.

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/bad-practices/cache-directory-options/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,78 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { withReviewMarkerAbove } from '../../../../../../utils/withReviewMarkerAbove';
+
+/**
+ * .what = a cache directory option that with-simple-cache 0.17.3 no longer accepts.
+ * .why  = `directoryToPersistTo` and `s3` left the options at 0.17.3; `directory` replaces both.
+ */
+const RETIRED_DIRECTORY_OPTION_PATTERN =
+  /^(?!\s*\/\/).*(?:\bdirectoryToPersistTo\b|\bs3\s*:(?!\/\/))/;
+
+/**
+ * .what = an `s3:` object key, the retired option.
+ * .why  = `(?!\/\/)` passes the `s3://` scheme of a uri, which the `directory.cloud.path` of
+ *         0.17.3 carries (e.g. the config practice's own getOneCacheDirectory template).
+ */
+const S3_KEY_PATTERN = /\bs3\s*:(?!\/\/)/;
+
+/**
+ * .what = a file's code lines, with each `//` comment line dropped.
+ * .why  = the review marker names both retired options, so the check must read code, not prose.
+ */
+const asCodeLines = (input: { contents: string }): string =>
+  input.contents
+    .split('\n')
+    .filter((line) => !line.trimStart().startsWith('//'))
+    .join('\n');
+
+/**
+ * .what = the hint that a file builds a cache directory, so an `s3:` key is the cache option.
+ */
+const CACHE_DIRECTORY_HINT_PATTERN =
+  /\bgetCacheDirectory\b|['"](?:with-simple-cache|simple-on-disk-cache)['"]/;
+
+const REVIEW_MARKER =
+  '// @declapract:review: with-simple-cache 0.17.3 retired `s3` and `directoryToPersistTo` — pass `directory` in their place, and `await` each cache `get()`, which now returns a Promise. then delete this marker';
+
+/**
+ * .what = whether a file declares a cache directory option retired at with-simple-cache 0.17.3.
+ */
+const isRetiredDirectoryOptionDeclared = (input: {
+  contents: string;
+}): boolean => {
+  const code = asCodeLines({ contents: input.contents });
+  return (
+    /\bdirectoryToPersistTo\b/.test(code) ||
+    (CACHE_DIRECTORY_HINT_PATTERN.test(code) && S3_KEY_PATTERN.test(code))
+  );
+};
+
+/**
+ * .what = flags a src file that still passes `s3` / `directoryToPersistTo` to the cache.
+ * .why  = the `cache` floor raises with-simple-cache to 0.17.3, which drops both options, so the
+ *         file fails to type-check with no pointer to the move (#644).
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (contents && isRetiredDirectoryOptionDeclared({ contents })) return; // bad practice detected
+  throw new Error(
+    'does not match bad practice: no retired cache directory option',
+  );
+};
+
+/**
+ * .what = stamps a review line above each retired option that names the `directory` move.
+ * .why  = the replacement shape depends on where the repo persists its cache, which a regex
+ *         cannot know, so the fix names the move and rewrites no code.
+ * .note = idempotent; the check stays red until a human moves the option.
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  return {
+    contents: withReviewMarkerAbove({
+      contents,
+      lineMatcher: RETIRED_DIRECTORY_OPTION_PATTERN,
+      marker: REVIEW_MARKER,
+    }),
+  };
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/bad-practices/unfloored-cache-member/.declapract.readme.md

@@ -0,0 +1,10 @@
+a cache family member that the `cache` best-practice holds no floor for.
+
+`.ifInstalled()` reads an undeclared member as "not used", so a member below any version passes
+`plan` unseen. this bad-practice names each such member instead.
+
+- a retired member (`with-simple-caching`) moves to its successor (`with-simple-cache`) once no src
+  file imports it; a src import of it gets a `// @declapract:review:` line that names the move
+- a member this practice does not know stays in place, named by `plan`, until a floor for it lands
+  in `cache/best-practice/package.json` (and in `CACHE_FAMILY_MEMBERS_FLOORED`, which a test holds
+  equal to those floors)

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/bad-practices/unfloored-cache-member/package.json.declapract.ts

@@ -0,0 +1,151 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { asPackageJSON } from '../../../../utils/asPackageJSON';
+import { isPackageImportedInRepo } from '../../../../utils/isPackageImportedInRepo';
+
+const PRACTICE = 'cache/unfloored-cache-member';
+
+/**
+ * .what = every cache family member the `cache` best-practice declares a floor for.
+ * .why  = `.ifInstalled()` reads an absent floor as "not used", so a member with no floor sits
+ *         below any version unseen (#625). this list is the declared set; a test asserts it equals
+ *         the floors in `best-practice/package.json`, so the two cannot drift apart.
+ */
+export const CACHE_FAMILY_MEMBERS_FLOORED = [
+  'simple-in-memory-cache',
+  'simple-localstorage-cache',
+  'simple-on-disk-cache',
+  'with-domain-driven-cache',
+  'with-domain-driven-caching',
+  'with-simple-cache',
+] as const;
+
+/**
+ * .what = retired cache family members, each mapped to the member that replaced it.
+ */
+const CACHE_FAMILY_MEMBERS_RETIRED: Record<
+  string,
+  { into: string; version: string }
+> = {
+  'with-simple-caching': { into: 'with-simple-cache', version: '0.17.3' },
+};
+
+/**
+ * .what = the shape of a cache family package name.
+ * .why  = a member the floors do not name is the gap #625 reports; this shape is how `plan` sees
+ *         a member the declaration never listed, so the next family member cannot slip past.
+ */
+const CACHE_FAMILY_PATTERN =
+  /^(?:simple-[a-z0-9-]+-cache|with-(?:simple|domain-driven)-cach(?:e|ing))$/;
+
+const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies'] as const;
+
+/**
+ * .what = whether src still imports a package.
+ */
+const isImportedInSrc = (input: {
+  packageName: string;
+  projectRoot: string | null;
+}): boolean =>
+  !!input.projectRoot &&
+  isPackageImportedInRepo({
+    projectRoot: input.projectRoot,
+    packageName: input.packageName,
+    dirs: ['src'],
+  });
+
+/**
+ * .what = the cache family members a package.json declares that hold no floor.
+ * .note = a retired member that src still imports is left out: it cannot move until the import
+ *         moves, and the `src/**` half of this bad-practice stamps that import with the move.
+ */
+const getCacheMembersUnfloored = (input: {
+  packageJSON: Record<string, any>;
+  projectRoot: string | null;
+}): string[] =>
+  DEPENDENCY_SECTIONS.flatMap((section) =>
+    Object.keys(input.packageJSON[section] ?? {}),
+  )
+    .filter((name) => CACHE_FAMILY_PATTERN.test(name))
+    .filter(
+      (name) =>
+        !(CACHE_FAMILY_MEMBERS_FLOORED as readonly string[]).includes(name),
+    )
+    .filter(
+      (name) =>
+        !CACHE_FAMILY_MEMBERS_RETIRED[name] ||
+        !isImportedInSrc({
+          packageName: name,
+          projectRoot: input.projectRoot,
+        }),
+    );
+
+/**
+ * .what = one dependency section, with each retired member moved to the member that replaced it.
+ * .note = an extant replacement version is the adopter's choice and is kept.
+ */
+const asSectionWithRetiredMoved = (input: {
+  section: Record<string, string | undefined>;
+  retired: string[];
+}): Record<string, string | undefined> =>
+  input.retired.reduce((deps, name) => {
+    if (!deps[name]) return deps;
+    const replacement = CACHE_FAMILY_MEMBERS_RETIRED[name]!;
+    return {
+      ...deps,
+      [name]: undefined, // undefined drops the key from the written json
+      [replacement.into]: deps[replacement.into] ?? replacement.version,
+    };
+  }, input.section);
+
+/**
+ * .what = flags a package.json that declares a cache family member with no floor.
+ * .why  = so `plan` names the member, rather than read its absence as a pass (#625).
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  const unfloored = getCacheMembersUnfloored({
+    packageJSON: asPackageJSON(
+      { contents: contents ?? '{}' },
+      { practice: PRACTICE },
+    ),
+    projectRoot: context?.getProjectRootDirectory?.() ?? null,
+  });
+  if (unfloored.length) return; // bad practice detected
+  throw new Error(
+    'does not match bad practice: every cache family member holds a floor',
+  );
+};
+
+/**
+ * .what = moves each retired member to the member that replaced it, in its own section.
+ * .note = a member this practice does not know is left in place for a human to floor here; `plan`
+ *         keeps it named until then.
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  if (!contents) return { contents };
+  const packageJSON = asPackageJSON({ contents }, { practice: PRACTICE });
+  const unfloored = getCacheMembersUnfloored({
+    packageJSON,
+    projectRoot: context?.getProjectRootDirectory?.() ?? null,
+  });
+  const retired = unfloored.filter(
+    (name) => CACHE_FAMILY_MEMBERS_RETIRED[name],
+  );
+  if (!retired.length) return { contents };
+
+  // move each retired member within each section that declares one
+  const updatedPackageJSON = DEPENDENCY_SECTIONS.reduce(
+    (current, section) =>
+      current[section]
+        ? {
+            ...current,
+            [section]: asSectionWithRetiredMoved({
+              section: current[section],
+              retired,
+            }),
+          }
+        : current,
+    packageJSON,
+  );
+  return { contents: JSON.stringify(updatedPackageJSON, null, 2) };
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/bad-practices/unfloored-cache-member/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,39 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { withReviewMarkerAbove } from '../../../../../../utils/withReviewMarkerAbove';
+
+/**
+ * .what = an import (or require) of the retired `with-simple-caching`.
+ */
+const RETIRED_CACHE_IMPORT_PATTERN =
+  /(?:\bfrom\s+|\brequire\(\s*|\bimport\(\s*)['"]with-simple-caching(?:\/[^'"]*)?['"]/;
+
+const REVIEW_MARKER =
+  '// @declapract:review: with-simple-caching is retired — import from with-simple-cache (>=0.17.3) in its place: its cache `get()` is async, and its on-disk `directory` option replaces `s3` / `directoryToPersistTo`. then delete this marker';
+
+/**
+ * .what = flags a src file that still imports `with-simple-caching`.
+ * .why  = the package.json half of this bad-practice moves the dep to with-simple-cache only once
+ *         no src file imports it (#625); this half names each import that holds the move back.
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (contents && RETIRED_CACHE_IMPORT_PATTERN.test(contents)) return; // bad practice detected
+  throw new Error(
+    'does not match bad practice: no import of with-simple-caching',
+  );
+};
+
+/**
+ * .what = stamps a review line above each such import that names the replacement.
+ * .note = idempotent; the check stays red until a human moves the import.
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  return {
+    contents: withReviewMarkerAbove({
+      contents,
+      lineMatcher: RETIRED_CACHE_IMPORT_PATTERN,
+      marker: REVIEW_MARKER,
+    }),
+  };
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/best-practice/.declapract.readme.md

@@ -0,0 +1,17 @@
+a version floor for each member of the cache package family, applied only where the member is
+installed (`.ifInstalled()`).
+
+`.ifInstalled()` reads an undeclared member as "not used", so every family member must hold a floor
+here; the `unfloored-cache-member` bad-practice names any member that does not.
+
+## with-simple-cache 0.17.3 — the contract moved
+
+the floor raises `with-simple-cache` to `0.17.3`. a consumer on `0.15.x` compiles against a changed
+contract:
+
+- `SimpleOnDiskCache.get()` returns `Promise<string | undefined>`; `await` each `get()` that a
+  `SimpleCache<string>` consumer read synchronously
+- the cache directory options lost `s3` and `directoryToPersistTo`; `directory` replaces both
+
+the `cache-directory-options` bad-practice stamps a `// @declapract:review:` line above each retired
+option it finds in `src/`.

package/dist/.test/assets/expo-fullusecase/declarations/practices/cache/best-practice/package.json

@@ -1,7 +1,10 @@
 {
   "dependencies": {
     "simple-in-memory-cache": "@declapract{check.minVersion('0.5.1').ifInstalled()}",
+    "simple-localstorage-cache": "@declapract{check.minVersion('1.0.1').ifInstalled()}",
     "simple-on-disk-cache": "@declapract{check.minVersion('1.8.1').ifInstalled()}",
+    "with-domain-driven-cache": "@declapract{check.minVersion('1.1.5').ifInstalled()}",
+    "with-domain-driven-caching": "@declapract{check.minVersion('1.1.4').ifInstalled()}",
     "with-simple-cache": "@declapract{check.minVersion('0.17.3').ifInstalled()}"
   }
 }