Merge pull request #780 from mk3008/778-scaffold-ルート境界をまたぐ-import-を-root-alias-に統一する

fix(ztd-cli): align scaffold cross-root imports with root aliases

Author: mk3008

.changeset/ten-soft-camels-jump.md

@@ -0,0 +1,7 @@
+---
+"@rawsql-ts/ztd-cli": patch
+---
+
+Align generated project root aliases across `package.json`, `tsconfig.json`, and `vitest.config.ts` so scaffolded code can use `#features/*`, `#libraries/*`, `#adapters/*`, and `#tests/*` consistently.
+
+Starter and scaffold templates now use root aliases for imports that cross canonical roots instead of deep relative paths, which makes generated projects easier to move and reorganize without rewriting import depth.

packages/ztd-cli/README.md

@@ -166,11 +166,9 @@ As boundary depth grows, avoid making every import depth-sensitive by default.
 
 - The goal is boundary-change safety, not a blanket root-alias migration.
 - Keep local, nearby references relative when they move with the same boundary.
-- Stabilize only shared references that are likely to break when work is split horizontally and moved into a deeper child boundary, such as `src/features/_shared/*` or `tests/support/*`.
-- One workable tactic is package `imports` or an equivalent alias that works in both TypeScript and runtime resolution, but that is a means, not the architectural goal.
-- Minimum rule: imports that cross boundaries should make the target boundary explicit and go through its `boundary.ts` entrypoint.
-- Pragmatic exception: designated shared seams such as `src/features/_shared/*` and `tests/support/*` may use stabilized root-level aliases or package-style imports because they are shared support seams, not another boundary's private internals.
-- Do not treat this issue as a reason to rewrite every scaffolded import to one style.
+- When an import crosses canonical roots, use the matching root alias so the target root stays explicit: `#features/*`, `#libraries/*`, `#adapters/*`, and `#tests/*`.
+- Feature-to-feature imports should still go through the target boundary's `boundary.ts` entrypoint rather than deep private files.
+- Root aliases are for cross-root references and shared seams, not a reason to rewrite every same-root local import to one style.
 
 ## Troubleshooting
 

packages/ztd-cli/src/commands/init.ts

@@ -2076,6 +2076,14 @@ function ensurePackageJsonFormatting(
       types: './src/features/*.ts',
       default: './dist/features/*.js'
     },
+    '#libraries/*.js': {
+      types: './src/libraries/*.ts',
+      default: './dist/libraries/*.js'
+    },
+    '#adapters/*.js': {
+      types: './src/adapters/*.ts',
+      default: './dist/adapters/*.js'
+    },
     '#tests/*.js': {
       types: './tests/*.ts',
       default: './tests/*.ts'

packages/ztd-cli/templates/README.md

@@ -36,6 +36,15 @@ The starter keeps `ztdRootDir`, `ddlDir`, `defaultSchema`, and `searchPath` in `
 
 `src/features/<feature>/tests/` is where feature-root boundary tests live. Query-local ZTD assets live under `src/features/<feature>/queries/<query>/tests/{generated,cases}` with the thin entrypoint beside them. Starter-owned shared support lives at `tests/support/ztd/`, while `.ztd/` is the tool-managed workspace for generated metadata and support files. Keep `FeatureQueryExecutor` in `src/features/_shared/`, keep the driver-neutral `SqlClient` contract in `src/libraries/sql/sql-client.ts`, and put driver or sink bindings under `src/adapters/<tech>/`.
 
+When an import crosses one of the canonical roots, use the root alias instead of a depth-sensitive relative path:
+
+- `#features/*` for `src/features/*`
+- `#libraries/*` for `src/libraries/*`
+- `#adapters/*` for `src/adapters/*`
+- `#tests/*` for `tests/*`
+
+Keep local same-root references relative when they move with the same boundary. Use the alias when the import crosses a root boundary or points at shared support.
+
 ## Getting Started with AI
 
 Use this short prompt:

packages/ztd-cli/templates/src/adapters/console/repositoryTelemetry.ts

@@ -2,7 +2,7 @@ import type {
   RepositoryTelemetry,
   RepositoryTelemetryConsoleOptions,
   RepositoryTelemetryEvent,
-} from '../../libraries/telemetry/types.js';
+} from '#libraries/telemetry/types.js';
 
 /**
  * Create a conservative console-backed telemetry hook for repositories.

packages/ztd-cli/templates/src/adapters/pg/sql-client.ts

@@ -1,4 +1,4 @@
-import type { SqlClient } from '../../libraries/sql/sql-client.js';
+import type { SqlClient } from '#libraries/sql/sql-client.js';
 
 /**
  * Adapt a `pg`-style queryable (Client or Pool) into a SqlClient.

packages/ztd-cli/templates/tests/support/testkit-client.webapi.ts

@@ -1,4 +1,4 @@
-import type { SqlClient } from '../../src/libraries/sql/sql-client.js';
+import type { SqlClient } from '#libraries/sql/sql-client.js';
 
 export type TestkitClient = SqlClient & {
   close(): Promise<void>;

packages/ztd-cli/templates/tsconfig.json

@@ -7,6 +7,8 @@
     "baseUrl": ".",
     "paths": {
       "#features/*": ["src/features/*"],
+      "#libraries/*": ["src/libraries/*"],
+      "#adapters/*": ["src/adapters/*"],
       "#tests/*": ["tests/*"]
     },
     "strict": true,

packages/ztd-cli/templates/vitest.config.ts

@@ -5,6 +5,8 @@ export default defineConfig({
   resolve: {
     alias: {
       '#features': fileURLToPath(new URL('./src/features', import.meta.url)),
+      '#libraries': fileURLToPath(new URL('./src/libraries', import.meta.url)),
+      '#adapters': fileURLToPath(new URL('./src/adapters', import.meta.url)),
       '#tests': fileURLToPath(new URL('./tests', import.meta.url)),
     },
   },

packages/ztd-cli/tests/directoryFinding.docs.test.ts

@@ -103,6 +103,15 @@ test('feature guidance centers the sample feature and recursive boundary folders
   );
   expect(readNormalizedFile('packages/ztd-cli/templates/src/libraries/sql/sql-client.ts')).toContain('SqlClient');
   expect(readNormalizedFile('packages/ztd-cli/templates/src/adapters/pg/sql-client.ts')).toContain('fromPg');
+  expect(readNormalizedFile('packages/ztd-cli/templates/src/adapters/pg/sql-client.ts')).toContain(
+    "from '#libraries/sql/sql-client.js'"
+  );
+  expect(readNormalizedFile('packages/ztd-cli/templates/src/adapters/console/repositoryTelemetry.ts')).toContain(
+    "from '#libraries/telemetry/types.js'"
+  );
+  expect(readNormalizedFile('packages/ztd-cli/templates/tests/support/testkit-client.webapi.ts')).toContain(
+    "from '#libraries/sql/sql-client.js'"
+  );
 });
 
 test('feature-first scaffold files exist in the template bundle', () => {