declapract-typescript-ehmpathy 0.49.12 → 0.49.14

package/dist/.test/assets/dates-and-times/declarations/practices/dates-and-times/bad-practices/uni-time/package.json.declapract.ts

@@ -0,0 +1,53 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+/**
+ * .what = the iso-time version the uni-time fix installs; the release the src fix's identifier
+ *         map was read against (iso-time's own uni-time migration table).
+ */
+const ISO_TIME_VERSION = '1.11.7';
+
+/**
+ * .what = one dependency section, with `@ehmpathy/uni-time` swapped for `iso-time` where it sat.
+ * .note = an extant `iso-time` version is kept; a section with no uni-time is returned as is.
+ */
+const asSectionWithUniTimeSwapped = (input: {
+  section: Record<string, string> | undefined;
+}): Record<string, string | undefined> | undefined => {
+  if (!input.section?.['@ehmpathy/uni-time']) return input.section;
+  return {
+    ...input.section,
+    '@ehmpathy/uni-time': undefined, // undefined drops the key from the written json
+    'iso-time': input.section['iso-time'] ?? ISO_TIME_VERSION,
+  };
+};
+
+/**
+ * .what = swap `@ehmpathy/uni-time` for `iso-time` in each dep section that held it.
+ * .why  = the src fix rewrites every `@ehmpathy/uni-time` import to `iso-time`; a package.json fix
+ *         that only removes the old dep leaves each rewritten file on a package that is not
+ *         installed, and tsc fails with `Cannot find module 'iso-time'` (#642). so `iso-time` lands
+ *         in the same section `@ehmpathy/uni-time` sat in.
+ * .note = an extant `iso-time` version is the adopter's choice and is kept. a section the repo
+ *         never declared is not added.
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents }; // pass through if contents absent
+  const packageJSON = JSON.parse(contents);
+
+  // swap the dep within each section, only where uni-time sat
+  const updatedPackageJSON = {
+    ...packageJSON,
+    dependencies: asSectionWithUniTimeSwapped({
+      section: packageJSON.dependencies,
+    }),
+    devDependencies: asSectionWithUniTimeSwapped({
+      section: packageJSON.devDependencies,
+    }),
+  };
+  return {
+    contents: JSON.stringify(updatedPackageJSON, null, 2),
+  };
+};

package/dist/.test/assets/dates-and-times/declarations/practices/dates-and-times/bad-practices/uni-time/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,49 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  if (contents?.includes("from '@ehmpathy/uni-time'")) return; // matches if it includes this
+  throw new Error('does not match bad practice'); // does not otherwise
+};
+
+/**
+ * .what = each uni-time identifier and its iso-time twin, per iso-time's own migration table.
+ * .why  = iso-time renamed every exported name (the `Iso{Unit}{Nature}` pattern), so a module swap
+ *         alone leaves each imported name unresolved (#662).
+ */
+const UNI_TO_ISO_IDENTIFIERS: Record<string, string> = {
+  UniDateTime: 'IsoTimeStamp',
+  UniDate: 'IsoDateStamp',
+  UniMonth: 'IsoMonthStamp',
+  UniTime: 'IsoTimeFloat',
+  UniDateRange: 'IsoDateStampRange',
+  UniDateTimeRange: 'IsoTimeStampRange',
+  UniDuration: 'IsoDuration',
+  isUniDateTime: 'isIsoTimeStamp',
+  isUniDate: 'isIsoDateStamp',
+  isUniMonth: 'isIsoMonthStamp',
+  asUniDateTime: 'asIsoTimeStamp',
+  asUniDate: 'asIsoDateStamp',
+};
+
+/**
+ * .what = rename each whole-word uni-time identifier to its iso-time twin.
+ * .why  = a word boundary on both sides keeps an identifier that merely holds a uni-time name
+ *         inside it (`CommunityUniDate`) untouched, and makes the map order-free.
+ */
+const withIsoIdentifiers = (input: { contents: string }): string =>
+  input.contents.replace(
+    new RegExp(`\\b(${Object.keys(UNI_TO_ISO_IDENTIFIERS).join('|')})\\b`, 'g'),
+    (name) => UNI_TO_ISO_IDENTIFIERS[name] ?? name,
+  );
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {}; // pass through if contents absent
+
+  // swap the module, then the names it exports
+  const withIsoModule = contents.replace(
+    /from '@ehmpathy\/uni-time'/g,
+    "from 'iso-time'",
+  );
+  return { contents: withIsoIdentifiers({ contents: withIsoModule }) };
+};

package/dist/.test/assets/dates-and-times/declarations/practices/dates-and-times/best-practice/.declapract.readme.md

@@ -0,0 +1 @@
+`date-fns` is a great library for manipulating dates and times in a functional, immutable, declarative pattern

package/dist/.test/assets/dates-and-times/declarations/practices/dates-and-times/best-practice/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "date-fns": "@declapract{check.minVersion('2.14.0')}"
+  }
+}

package/dist/.test/assets/dates-and-times/declarations/useCases.yml

@@ -0,0 +1,5 @@
+# minimal use case for the dates-and-times practice integration test
+use-cases:
+  lambda-service:
+    practices:
+      - dates-and-times

package/dist/.test/assets/directory-structure-src/declarations/declapract.declare.yml

@@ -0,0 +1,4 @@
+# minimal declarations for the directory-structure-src integration test
+declare:
+  practices: practices
+  use-cases: useCases.yml

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/.declapract.integration.test.ts

@@ -0,0 +1,98 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+// executeApply is slow (full practice evaluation), so grant a generous limit
+jest.setTimeout(180_000);
+
+/**
+ * .what = end-to-end proof of the domain barrel move and the bare barrel import repoint (#655, #671).
+ * .why  = two barrels (`domain/index.ts` → `./objects`, and `domain/objects/index.ts`) both move onto
+ *   `domain.objects/index.ts`; the outer one, stripped, held no export and could win the path. and
+ *   a bare `'@src/domain'` / `'../domain'` import matched neither the check nor the fix. only the real
+ *   pipeline proves which file lands on the shared path.
+ * .note = the outer barrel is applied AFTER the inner one — the order in which it used to win.
+ */
+describe('directory-structure-src domain barrels and bare barrel imports', () => {
+  given('[case1] a repo with two domain barrels and bare barrel imports', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-dirs-two-barrels',
+      clone: './src/.test/assets/directory-structure-src/demo-repo-with-two-domain-barrels',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/directory-structure-src/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const isPresent = (relativePath: string) =>
+      fs
+        .access(path.join(tempDir, relativePath))
+        .then(() => true)
+        .catch(() => false);
+    const applyOne = (input: { file: string }) =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'directory-structure-src',
+        file: input.file,
+      });
+
+    when('[t0] the input (before any fix)', () => {
+      then('the barrels and the importer match snapshot', async () => {
+        expect(await read('src/domain/index.ts')).toMatchSnapshot('outer barrel — before');
+        expect(await read('src/domain/objects/index.ts')).toMatchSnapshot('inner barrel — before');
+        expect(await read('src/domain.operations/getQuote.ts')).toMatchSnapshot('importer — before');
+      });
+    });
+
+    when('[t1] the moves and the import repoint are applied', () => {
+      const after = useThen('apply, outer barrel last', async () => {
+        await applyOne({ file: 'src/domain/objects/index.ts' });
+        await applyOne({ file: 'src/domain/objects/Quote.ts' });
+        await applyOne({ file: 'src/domain/index.ts' });
+        await applyOne({ file: 'src/domain.operations/getQuote.ts' });
+        return {
+          barrel: await read('src/domain.objects/index.ts'),
+          importer: await read('src/domain.operations/getQuote.ts'),
+          outerPresent: await isPresent('src/domain/index.ts'),
+          quotePresent: await isPresent('src/domain.objects/Quote.ts'),
+        };
+      });
+
+      then('domain.objects/index.ts holds the inner barrel list, never the stripped outer one (#655)', () => {
+        expect(after.barrel).toContain("export * from './Quote';");
+        expect(after.outerPresent).toBe(false);
+        expect(after.quotePresent).toBe(true);
+        expect(after.barrel).toMatchSnapshot('domain.objects/index.ts — after');
+      });
+
+      then('each bare barrel import is repointed, and a package subpath is left alone (#655, #671)', () => {
+        expect(after.importer).toContain("from '@src/domain.objects';");
+        expect(after.importer).toContain("from '../domain.objects';");
+        expect(after.importer).toContain("from 'some-pkg/domain';");
+        expect(after.importer).toMatchSnapshot('importer — after');
+      });
+    });
+
+    when('[t2] the importer and the barrel are applied a second time (idempotency)', () => {
+      const passes = useThen('a second apply over its own output', async () => {
+        const files = ['src/domain.objects/index.ts', 'src/domain.operations/getQuote.ts'];
+        const before = await Promise.all(files.map((file) => read(file)));
+        await applyOne({ file: files[0]! });
+        await applyOne({ file: files[1]! });
+        const after = await Promise.all(files.map((file) => read(file)));
+        return { before, after };
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,37 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`directory-structure-src domain barrels and bare barrel imports given: [case1] a repo with two domain barrels and bare barrel imports when: [t0] the input (before any fix) then: the barrels and the importer match snapshot: importer — before 1`] = `
+"import type { Quote } from '@src/domain';
+import type { Quote as QuoteRelative } from '../domain';
+import type { Widget } from 'some-pkg/domain';
+
+export const getQuote = (input: { quote: Quote; peer: QuoteRelative; widget: Widget }) =>
+  input.quote;
+"
+`;
+
+exports[`directory-structure-src domain barrels and bare barrel imports given: [case1] a repo with two domain barrels and bare barrel imports when: [t0] the input (before any fix) then: the barrels and the importer match snapshot: inner barrel — before 1`] = `
+"export * from './Quote';
+"
+`;
+
+exports[`directory-structure-src domain barrels and bare barrel imports given: [case1] a repo with two domain barrels and bare barrel imports when: [t0] the input (before any fix) then: the barrels and the importer match snapshot: outer barrel — before 1`] = `
+"// export * from './constants';
+export * from './objects';
+"
+`;
+
+exports[`directory-structure-src domain barrels and bare barrel imports given: [case1] a repo with two domain barrels and bare barrel imports when: [t1] the moves and the import repoint are applied then: domain.objects/index.ts holds the inner barrel list, never the stripped outer one (#655): domain.objects/index.ts — after 1`] = `
+"export * from './Quote';
+"
+`;
+
+exports[`directory-structure-src domain barrels and bare barrel imports given: [case1] a repo with two domain barrels and bare barrel imports when: [t1] the moves and the import repoint are applied then: each bare barrel import is repointed, and a package subpath is left alone (#655, #671): importer — after 1`] = `
+"import type { Quote } from '@src/domain.objects';
+import type { Quote as QuoteRelative } from '../domain.objects';
+import type { Widget } from 'some-pkg/domain';
+
+export const getQuote = (input: { quote: Quote; peer: QuoteRelative; widget: Widget }) =>
+  input.quote;
+"
+`;

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/bad-practices/data-dir/.declapract.readme.md

@@ -0,0 +1,10 @@
+the `src/data/` directory pattern is deprecated
+
+use `src/access/` instead, which contains:
+- `daos/` - data access objects for persistence
+- `sdks/` - third party remote service contracts
+- `svcs/` - first party remote service contracts
+
+this aligns with the directional-dependencies architecture where:
+- `access/` may depend on `domain.objects/` and `domain.operations/`
+- `access/` must remain free of domain knowledge and business rules

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/bad-practices/data-dir/src/<star><star>/data/<star><star>/<star>.declapract.ts

@@ -0,0 +1,19 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+// if files exist in any /data/, this is a bad practice
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = (contents, context) => {
+  // move any /data/dao/* to /access/daos/*
+  // move any /data/clients/* to /access/sdks/*
+  // move other /data/* to /access/*
+  const newPath = context.relativeFilePath
+    .replace(/\/data\/dao\//g, '/access/daos/')
+    .replace(/\/data\/clients\//g, '/access/sdks/')
+    .replace(/\/data\//g, '/access/');
+
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/bad-practices/domain-dir/.declapract.readme.md

@@ -0,0 +1,8 @@
+the `src/domain/` directory pattern is deprecated
+
+use `src/domain.objects/` instead for domain object declarations
+
+this aligns with the directional-dependencies architecture where:
+- `domain.objects/` contains canonical domain declarations
+- `domain.objects/` must not depend on anything outside its own layer
+- separates domain objects from domain operations for clearer boundaries

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/bad-practices/domain-dir/src/<star><star>/domain/<star><star>/<star>.declapract.ts

@@ -0,0 +1,107 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+// if files exist in any /domain/, this is a bad practice
+export const check = FileCheckType.EXISTS;
+
+/**
+ * .what = whether a file is an outer `domain/index.ts` barrel that only forwards `./objects`,
+ *         beside an inner `domain/objects/index.ts` barrel.
+ * .why  = both barrels move onto one path, `domain.objects/index.ts`. the outer one, once its
+ *         `./objects` forward is stripped, holds no export — and if it wins the path, every domain
+ *         export vanishes from the barrel with no error (#655). the inner barrel holds the real
+ *         list, so the outer one must yield the path to it.
+ */
+const isOuterBarrelBesideInner = (input: {
+  contents: string | null;
+  relativeFilePath: string;
+  projectRoot: string | null;
+}): boolean => {
+  if (!input.contents || !input.projectRoot) return false;
+  if (!/(?:^|\/)domain\/index\.ts$/.test(input.relativeFilePath)) return false;
+  const codeOnly = input.contents
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^\s*\/\/.*$/gm, '')
+    .trim();
+  if (!/^export\s+\*\s+from\s+['"]\.\/objects['"];?$/.test(codeOnly))
+    return false;
+  // the inner barrel, before its move or after it (apply order is not guaranteed)
+  const domainDir = path.join(
+    input.projectRoot,
+    path.dirname(input.relativeFilePath),
+  );
+  return (
+    existsSync(path.join(domainDir, 'objects', 'index.ts')) ||
+    existsSync(path.join(path.dirname(domainDir), 'domain.objects', 'index.ts'))
+  );
+};
+
+export const fix: FileFixFunction = (contents, context) => {
+  // an outer barrel that only forwards ./objects yields the path to the inner barrel (#655)
+  if (
+    isOuterBarrelBesideInner({
+      contents,
+      relativeFilePath: context.relativeFilePath,
+      projectRoot: context.getProjectRootDirectory?.() ?? null,
+    })
+  )
+    return { contents: null };
+
+  // move any /domain/objects/* to /domain.objects/*
+  // move any /domain/* to /domain.objects/*
+  // .note = the lookahead leaves the slash after each segment unconsumed, so adjacent segments
+  //         (`/domain/domain/`) each move. a consumed slash left the second `domain` segment in
+  //         place, which the `src/**/domain/**/*` glob then matched again on the next apply.
+  const newPath = context.relativeFilePath
+    .replace(/\/domain\/objects(?=\/)/g, '/domain.objects')
+    .replace(/\/domain(?=\/)/g, '/domain.objects');
+
+  let fixedContents = contents;
+
+  // fix relative imports for files DIRECTLY in domain/objects/ that move to domain.objects/
+  // these files move UP one directory level, so reduce ../ by one
+  // note: nested files (domain/objects/nested/Deep.ts) stay at same depth, no transform
+  const isDirectChildOfDomainObjects = /\/domain\/objects\/[^/]+$/.test(
+    context.relativeFilePath,
+  );
+  if (fixedContents && isDirectChildOfDomainObjects) {
+    fixedContents = fixedContents.replace(
+      /((?:import|export)[^'"]*['"])((?:\.\.\/)+)/g,
+      (match, importPrefix, dotDots) => {
+        const count = dotDots.split('../').length - 1;
+        if (count === 1) {
+          // '../X' → './X'
+          return `${importPrefix}./`;
+        }
+        // '../../X' → '../X', '../../../X' → '../../X', etc.
+        return `${importPrefix}${'../'.repeat(count - 1)}`;
+      },
+    );
+  }
+
+  // fix internal export paths in index files
+  // when domain/index.ts moves to domain.objects/index.ts,
+  // exports like './objects/User' should become './User'
+  if (
+    fixedContents &&
+    context.relativeFilePath.includes('/domain/') &&
+    context.relativeFilePath.endsWith('/index.ts')
+  ) {
+    fixedContents = fixedContents
+      // export * from './objects' → remove (objects dir flattened to root)
+      .replace(/export\s+\*\s+from\s+['"]\.\/objects['"];?\n?/g, '')
+      // ./objects/Foo → ./Foo
+      .replace(/(['"])\.\/objects\//g, '$1./')
+      // ../domain/objects/Foo → ../domain.objects/Foo (for cross-references)
+      .replace(/(['"])([^'"]*?)\/domain\/objects\//g, '$1$2/domain.objects/')
+      // ../domain/Foo → ../domain.objects/Foo
+      .replace(/(['"])([^'"]*?)\/domain\//g, '$1$2/domain.objects/');
+  }
+
+  return {
+    contents: fixedContents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/bad-practices/logic-dir/.declapract.readme.md

@@ -0,0 +1,8 @@
+the `src/logic/` directory pattern is deprecated
+
+use `src/domain.operations/` instead for domain behavior and business rules
+
+this aligns with the directional-dependencies architecture where:
+- `domain.operations/` contains domain behavior and business rules
+- `domain.operations/` may depend on `domain.objects/` or `infra/`
+- `domain.operations/` must not reference infrastructure concerns directly

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/bad-practices/logic-dir/src/<star><star>/logic/<star><star>/<star>.declapract.ts

@@ -0,0 +1,19 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+/**
+ * .what = moves any file from any /logic/ to /domain.operations/
+ * .why = ensures all files are moved, not just .ts files — prevents silent data loss for hidden paths
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  const newPath = context.relativeFilePath.replace(
+    /\/logic\//g,
+    '/domain.operations/',
+  );
+
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/bad-practices/model-dir/.declapract.readme.md

@@ -0,0 +1,3 @@
+we use `domain.objects` directory instead of `model` directory
+- model directory was what we originally went with, but realized `domain.objects` was more explicit and better represented what we were going after
+- files are migrated directly from `src/model/` to `src/domain.objects/`

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/bad-practices/model-dir/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,46 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+const defineModelImportFromRelativePathName = ({
+  relativeFilePath,
+}: {
+  relativeFilePath: string;
+}) => {
+  const directoriesDeepFromSrc = relativeFilePath.split('/').slice(1, -1); // all the directories between src/ and the /fileName
+  const badImportPath = `${directoriesDeepFromSrc
+    .map(() => '..')
+    .join('/')}/model`;
+  const badImportStatementIdentifierToReplace = `from '${badImportPath}`; // notice that we dont close the `'` so that we can match `.../model/some/other/stuff';`
+  return badImportStatementIdentifierToReplace;
+};
+
+/**
+ * check they dont import from the model dir
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  const badImportIdentifier = defineModelImportFromRelativePathName({
+    relativeFilePath: context.relativeFilePath,
+  });
+  if (contents?.includes(badImportIdentifier)) return; // relative import to model dir
+  if (contents?.includes(`@src/model`)) return; // absolute @src/model import
+  if (contents?.includes(`/domain/domainObjects`)) return; // matches bad practice if it has import to `.../domainObjects/...` as well
+  throw new Error('does not match bad practice'); // TODO: make this less weird... its weird that we throw an error when its not bad practice
+};
+
+/**
+ * replace `.../model` imports with `.../domain.objects` imports
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  const badImportIdentifier = defineModelImportFromRelativePathName({
+    relativeFilePath: context.relativeFilePath,
+  });
+  if (!contents) return {}; // do nothing if no contents, fn shouldn't have been called in this case
+  return {
+    contents: contents
+      .replace(
+        badImportIdentifier,
+        badImportIdentifier.replace('/model', '/domain.objects'), // should be referencing the domain.objects dir instead
+      )
+      .replace(/@src\/model\b/g, '@src/domain.objects') // fix absolute @src/model imports
+      .replace(/\/domainObjects/g, ''), // remove the domainObjects subdir as domain.objects is flat now
+  };
+};

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/bad-practices/model-dir/src/<star><star>/model/<star><star>/<star>.declapract.ts

@@ -0,0 +1,16 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if we see that files with this path exist, its bad practice
+
+export const fix: FileFixFunction = (contents, context) => {
+  return {
+    contents:
+      contents?.replace(
+        "export * from './domainObjects';", // if it has this, we want to replace it
+        "export * from './';",
+      ) ?? null,
+    relativeFilePath: context.relativeFilePath
+      .replace(/\/model\/domainObjects\//g, '/domain.objects/')
+      .replace(/\/model\//g, '/domain.objects/'),
+  };
+};

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/bad-practices/nonpublished-modules-dir/src/__nonpublished_modules__/<star><star>/<star>.declapract.ts

@@ -0,0 +1,17 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+// if files exist in __nonpublished_modules__/, this is a bad practice
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = (contents, context) => {
+  // move any /__nonpublished_modules__/ to /_topublish/
+  const newPath = context.relativeFilePath.replace(
+    /__nonpublished_modules__\//g,
+    '_topublish/',
+  );
+
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/bad-practices/old-import-paths/.declapract.readme.md

@@ -0,0 +1,21 @@
+imports referencing old directory structure paths should be updated
+
+old → new:
+- `src/data/dao` → `src/access/daos`
+- `src/data/clients` → `src/access/sdks`
+- `src/data/` → `src/access/`
+- `src/domain/objects` → `src/domain.objects`
+- `src/domain/` → `src/domain.objects/`
+- `src/logic/` → `src/domain.operations/`
+
+this bad practice checks all source files for imports using the old paths and fixes them.
+
+## two-pass migration
+
+a file still under a deprecated src dir is **deferred** this pass — the import rewrite is held to
+the next `declapract fix` pass. that is because the peer `old-*-dir` bad-practices RELOCATE the file
+this pass; a relocate plus an in-place rewrite of one file in one apply throws ENOENT on the unlinked
+source. so a consumer who migrates a repo that still holds `logic/` / `data/` / etc. must **run
+`declapract fix` twice**: pass 1 relocates the files, pass 2 rewrites their imports at the new path.
+the guard is shared with `typescript-any/relative-imports` via
+`src/utils/isDeferredToDeprecatedDirMove.ts`, so the two rewriters defer the same files.

package/dist/.test/assets/directory-structure-src/declarations/practices/directory-structure-src/bad-practices/old-import-paths/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,93 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import {
+  hasBareDeprecatedDirSpecifier,
+  withBareDeprecatedDirSpecifiersRepointed,
+} from '../../../../../../utils/asBareDeprecatedDirSpecifierReplacement';
+import { isDeferredToDeprecatedDirMove } from '../../../../../../utils/isDeferredToDeprecatedDirMove';
+
+// patterns to detect old import paths
+const OLD_PATH_PATTERNS = [
+  /from\s+['"][^'"]*\/data\/dao/,
+  /from\s+['"][^'"]*\/data\/clients/,
+  /from\s+['"][^'"]*\/data\//,
+  /from\s+['"][^'"]*\/domain\/objects/,
+  /from\s+['"][^'"]*\/domain\//,
+  /from\s+['"][^'"]*\/logic\//,
+  /from\s+['"][^'"]*\/model\/domainObjects/,
+  /from\s+['"][^'"]*\/model\//,
+  /from\s+['"][^'"]*\/services\//,
+  /from\s+['"][^'"]*\/__nonpublished_modules__\//,
+];
+
+/**
+ * .what = each slash-suffixed old dir specifier, repointed at its new dir
+ * .note = ordered most specific first, so `/data/dao` is read before `/data/`
+ */
+const withOldDirSpecifiersRepointed = (input: { contents: string }): string =>
+  input.contents
+    // data layer fixes
+    .replace(/(['"])([^'"]*?)\/data\/dao\b/g, '$1$2/access/daos')
+    .replace(/(['"])([^'"]*?)\/data\/clients\b/g, '$1$2/access/sdks')
+    .replace(/(['"])([^'"]*?)\/data\//g, '$1$2/access/')
+    // domain layer fixes
+    .replace(/(['"])([^'"]*?)\/domain\/objects\b/g, '$1$2/domain.objects')
+    .replace(/(['"])([^'"]*?)\/domain\//g, '$1$2/domain.objects/')
+    // logic layer fixes
+    .replace(/(['"])([^'"]*?)\/logic\//g, '$1$2/domain.operations/')
+    // model layer fixes (old structure before domain.objects)
+    .replace(/(['"])([^'"]*?)\/model\/domainObjects\b/g, '$1$2/domain.objects')
+    .replace(/(['"])([^'"]*?)\/model\//g, '$1$2/domain.objects/')
+    // services layer fixes (services = business logic, not service clients)
+    .replace(/(['"])([^'"]*?)\/services\//g, '$1$2/domain.operations/')
+    // nonpublished modules dir fix
+    .replace(
+      /(['"])([^'"]*?)\/__nonpublished_modules__\//g,
+      '$1$2/_topublish/',
+    );
+
+export const check: FileCheckFunction = (contents, context) => {
+  if (!contents) throw new Error('no contents');
+
+  // defer a file still under a deprecated dir to its peer dir-move: the move
+  // relocates it this pass, then this rewrite fires at the new path next pass.
+  // the two never touch one file in one apply, so no relocate+rewrite ENOENT.
+  if (
+    isDeferredToDeprecatedDirMove({
+      relativeFilePath: context?.relativeFilePath,
+    })
+  )
+    throw new Error('deferred to peer dir-move this pass');
+
+  // check if any old import path pattern matches
+  const hasOldImport = OLD_PATH_PATTERNS.some((pattern) =>
+    pattern.test(contents),
+  );
+  if (hasOldImport) return; // matches bad practice
+
+  // a bare barrel import ('@src/domain', '../../domain') — the same specifier set the fix repoints (#671)
+  if (
+    hasBareDeprecatedDirSpecifier({
+      contents,
+      relativeFilePath: context?.relativeFilePath ?? null,
+    })
+  )
+    return; // matches bad practice
+
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = (contents, context) => {
+  if (!contents) return { contents };
+
+  // repoint each bare barrel import first, so the slash-suffixed rewrites below never see it (#655)
+  const barrelsRepointed = withBareDeprecatedDirSpecifiersRepointed({
+    contents,
+    relativeFilePath: context?.relativeFilePath ?? null,
+  });
+
+  // repoint each slash-suffixed old dir specifier
+  return {
+    contents: withOldDirSpecifiersRepointed({ contents: barrelsRepointed }),
+  };
+};