@craft-ts/dev-tools 0.7.0-beta.13 → 0.7.0-beta.16

package/src/scripts/architecture/migrate-architecture.ts

@@ -1,653 +0,0 @@
-import { existsSync } from 'node:fs';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join, relative, resolve } from 'node:path';
-import {
-  architectureCatalogToTypeScript,
-  buildArchitectureCatalog,
-} from '../architecture-graph.js';
-import {
-  analyzeDependencyGraph,
-  type DependencyGraph,
-} from '../dependency-graph.js';
-
-export type MigrateArchitectureOptions = {
-  rootDir?: string;
-  tsConfigFilePath?: string;
-  write?: boolean;
-  check?: boolean;
-  json?: boolean;
-  jsonFilePath?: string;
-  log?: (message: string) => void;
-};
-
-export type MigrateArchitectureResult = {
-  changedFiles: string[];
-  exitCode: number;
-};
-
-type ArchitectureContext = {
-  appRoot: string;
-  workspaceRoot: string;
-  sourceGlob: string;
-  projectName: string;
-  nx: boolean;
-  graphTsConfigRel: string;
-  workspaceFromArchitecture: string;
-};
-
-const RULES = [
-  {
-    file: 'craft-unique.spec.ts',
-    helper: 'assertCraftUnique',
-    describe: 'assertCraftUnique',
-    it: 'requires craftUnique identities to appear once',
-    call: 'assertCraftUnique(graph.graph)',
-  },
-  {
-    file: 'http-endpoint-unique.spec.ts',
-    helper: 'assertHttpEndpointUnique',
-    describe: 'assertHttpEndpointUnique',
-    it: 'owns each HTTP endpoint once',
-    call: 'assertHttpEndpointUnique(graph.graph)',
-  },
-  {
-    file: 'craft-computed-pure.spec.ts',
-    helper: 'assertCraftComputedPure',
-    describe: 'assertCraftComputedPure',
-    it: 'keeps craftComputed free of methods and source$ writes',
-    call: 'assertCraftComputedPure(graph.graph)',
-  },
-  {
-    file: 'no-dependency-cycles.spec.ts',
-    helper: 'assertNoDependencyCycles',
-    describe: 'assertNoDependencyCycles',
-    it: 'forbids depends-on cycles',
-    call: 'assertNoDependencyCycles(graph.graph)',
-  },
-  {
-    file: 'app-config-route-cycles.spec.ts',
-    helper: 'assertNoAppConfigRouteCycles',
-    describe: 'assertNoAppConfigRouteCycles',
-    it: 'keeps app configuration and route modules acyclic',
-    call: 'assertNoAppConfigRouteCycles(graph.graph)',
-  },
-  {
-    file: 'route-di-proofs.spec.ts',
-    helper: 'assertRouteDiProofs',
-    describe: 'assertRouteDiProofs',
-    it: 'requires a DI proof on every routed component and app-config error screen',
-    call: 'assertRouteDiProofs(graph.graph)',
-  },
-  {
-    file: 'mutation-react-on.spec.ts',
-    helper: 'assertMutationHasReactOn',
-    describe: 'assertMutationHasReactOn',
-    it: 'requires a query to react to each mutation',
-    call: 'assertMutationHasReactOn(graph.graph)',
-  },
-  {
-    file: 'persisted-primitive-unique.spec.ts',
-    helper: 'assertPersistedPrimitiveHasUnique',
-    describe: 'assertPersistedPrimitiveHasUnique',
-    it: 'requires craftUnique on every persisted primitive',
-    call: 'assertPersistedPrimitiveHasUnique(graph.graph)',
-  },
-  {
-    file: 'insert-select-unique.spec.ts',
-    helper: 'assertInsertSelectUnique',
-    describe: 'assertInsertSelectUnique',
-    it: 'keeps insertSelect keys unique on each host',
-    call: 'assertInsertSelectUnique(graph.graph)',
-  },
-  {
-    file: 'craft-effect-no-network.spec.ts',
-    helper: 'assertCraftEffectNoNetwork',
-    describe: 'assertCraftEffectNoNetwork',
-    it: 'keeps craftEffect off HTTP and mutations',
-    call: 'assertCraftEffectNoNetwork(graph.graph)',
-  },
-  {
-    file: 'craft-effect-no-imperative-sync.spec.ts',
-    helper: 'assertCraftEffectNoImperativeSync',
-    describe: 'assertCraftEffectNoImperativeSync',
-    it: 'keeps craftEffect from pushing into state, sources, queries or mutations',
-    call: 'assertCraftEffectNoImperativeSync(graph.graph)',
-  },
-  {
-    file: 'interactive-element-named.spec.ts',
-    helper: 'assertInteractiveElementNamed',
-    describe: 'assertInteractiveElementNamed',
-    it: 'requires a unique literal data-craft-name on every interactive element',
-    call: 'assertInteractiveElementNamed(graph.graph)',
-  },
-] as const;
-
-export async function runArchitectureMigration(
-  options: MigrateArchitectureOptions = {},
-): Promise<MigrateArchitectureResult> {
-  const context = await resolveContext(options);
-  const files = buildScaffoldFiles(context);
-  const changedFiles = Object.keys(files).map((relativePath) =>
-    join(context.appRoot, relativePath),
-  );
-  changedFiles.push(join(context.appRoot, 'architecture/catalog.ts'));
-  const packagePath = findPackageJson(context.appRoot, context.workspaceRoot);
-  const projectPath = join(context.appRoot, 'project.json');
-  if (!context.nx && packagePath) {
-    changedFiles.push(packagePath);
-  }
-  if (context.nx && existsSync(projectPath)) {
-    changedFiles.push(projectPath);
-  }
-  const tsconfigPath = join(context.appRoot, 'tsconfig.json');
-  if (existsSync(tsconfigPath)) changedFiles.push(tsconfigPath);
-  const eslintPath = findEslintConfig(context.appRoot, context.workspaceRoot);
-  if (eslintPath) changedFiles.push(eslintPath);
-
-  if (options.write) {
-    const graphConfig = files['tsconfig.graph.json'];
-    if (graphConfig) {
-      await mkdir(context.appRoot, { recursive: true });
-      await writeFile(join(context.appRoot, 'tsconfig.graph.json'), graphConfig, 'utf8');
-    }
-  }
-
-  files['architecture/catalog.ts'] = await generateCatalog(context);
-
-  if (options.write) {
-    for (const [relativePath, contents] of Object.entries(files)) {
-      const fullPath = join(context.appRoot, relativePath);
-      await mkdir(dirname(fullPath), { recursive: true });
-      await writeFile(fullPath, contents, 'utf8');
-    }
-    if (!context.nx && packagePath) {
-      await patchPackageJson(packagePath, context);
-    }
-    if (context.nx) {
-      await patchNxProject(context);
-    }
-    await patchTsconfigReferences(context.appRoot);
-    await patchEslintIgnore(context.appRoot, context.workspaceRoot);
-  }
-
-  const exitCode =
-    options.check && !(await scaffoldMatches(context, files)) ? 1 : 0;
-
-  const result: MigrateArchitectureResult = {
-    changedFiles,
-    exitCode,
-  };
-
-  if (options.jsonFilePath) {
-    const path = resolve(options.jsonFilePath);
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
-  }
-  const log = options.log ?? console.log;
-  if (options.json) log(JSON.stringify(result, null, 2));
-  else {
-    log(
-      `${options.write ? 'Wrote' : 'Would write'} architecture suite: ${result.changedFiles.length} file(s).`,
-    );
-  }
-
-  return result;
-}
-
-async function resolveContext(
-  options: MigrateArchitectureOptions,
-): Promise<ArchitectureContext> {
-  const rootDir = resolve(options.rootDir ?? process.cwd());
-  const tsConfigFilePath = options.tsConfigFilePath
-    ? resolve(options.tsConfigFilePath)
-    : defaultTsConfig(rootDir);
-  const appRoot = dirname(tsConfigFilePath);
-  const workspaceRoot = findWorkspaceRoot(appRoot);
-  const nx = existsSync(join(appRoot, 'project.json'));
-  const sourceRel = posixRelative(appRoot, rootDir);
-  const sourceGlob =
-    !sourceRel || sourceRel === '.' ? 'src' : sourceRel.replace(/\\/g, '/');
-  const projectName = await readProjectName(appRoot, nx);
-  return {
-    appRoot,
-    workspaceRoot,
-    sourceGlob,
-    projectName,
-    nx,
-    graphTsConfigRel: posixRelative(
-      workspaceRoot,
-      join(appRoot, 'tsconfig.graph.json'),
-    ),
-    workspaceFromArchitecture: posixRelative(
-      join(appRoot, 'architecture'),
-      workspaceRoot,
-    ),
-  };
-}
-
-function buildScaffoldFiles(
-  context: ArchitectureContext,
-): Record<string, string> {
-  return {
-    'tsconfig.graph.json': `${JSON.stringify(
-      {
-        extends: './tsconfig.json',
-        compilerOptions: { skipLibCheck: true },
-        include: [`${context.sourceGlob}/**/*.ts`],
-        exclude: [
-          `${context.sourceGlob}/**/*.spec.ts`,
-          `${context.sourceGlob}/**/*.test.ts`,
-        ],
-      },
-      null,
-      2,
-    )}\n`,
-    'tsconfig.architecture.json': `${JSON.stringify(
-      {
-        extends: './tsconfig.json',
-        compilerOptions: {
-          types: ['node', 'vitest/globals'],
-          module: 'esnext',
-          moduleResolution: 'bundler',
-        },
-        include: ['architecture/**/*.ts'],
-      },
-      null,
-      2,
-    )}\n`,
-    'vitest.architecture.config.ts': vitestConfig(context),
-    'architecture/load-graph.ts': loadGraphSource(context),
-    'architecture/architecture.spec.ts': architectureSpecSource(),
-    ...Object.fromEntries(
-      RULES.map((rule) => [
-        `architecture/rules/${rule.file}`,
-        ruleSpecSource(rule),
-      ]),
-    ),
-  };
-}
-
-async function generateCatalog(context: ArchitectureContext): Promise<string> {
-  const header = '// Generated. Do not edit.\n';
-  try {
-    const graph = analyzeDependencyGraph({
-      rootDir: context.workspaceRoot,
-      tsConfigFilePath: context.graphTsConfigRel,
-    });
-    return `${header}${architectureCatalogToTypeScript(buildArchitectureCatalog(graph))}`;
-  } catch {
-    const empty: DependencyGraph = {
-      version: 1,
-      rootDir: context.workspaceRoot,
-      tsConfigFilePath: join(context.workspaceRoot, context.graphTsConfigRel),
-      nodes: [],
-      edges: [],
-    };
-    return `${header}${architectureCatalogToTypeScript(buildArchitectureCatalog(empty))}`;
-  }
-}
-
-function loadGraphSource(context: ArchitectureContext): string {
-  return `import { writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import {
-  analyzeDependencyGraph,
-  architectureCatalogToTypeScript,
-  buildArchitectureCatalog,
-  createArchitectureGraph,
-} from '@craft-ts/dev-tools';
-import { architectureCatalog } from './catalog';
-
-const workspaceRoot = resolve(import.meta.dirname, '${context.workspaceFromArchitecture}');
-const catalogPath = join(import.meta.dirname, 'catalog.ts');
-
-let cached: ReturnType<typeof createArchitectureGraph> | undefined;
-
-export function loadArchitectureGraph() {
-  if (cached) return cached;
-  const graph = analyzeDependencyGraph({
-    rootDir: workspaceRoot,
-    tsConfigFilePath: '${context.graphTsConfigRel}',
-  });
-  writeFileSync(
-    catalogPath,
-    \`// Generated. Do not edit.\\n\${architectureCatalogToTypeScript(buildArchitectureCatalog(graph))}\`,
-  );
-  cached = createArchitectureGraph(graph, architectureCatalog);
-  return cached;
-}
-`;
-}
-
-function architectureSpecSource(): string {
-  return `import { beforeAll, describe, expect, it } from 'vitest';
-import { loadArchitectureGraph } from './load-graph';
-
-/**
- * App-specific lookups. Common architecture rules live in \`rules/\`.
- */
-describe('architecture', () => {
-  let graph: ReturnType<typeof loadArchitectureGraph>;
-
-  beforeAll(() => {
-    graph = loadArchitectureGraph();
-  }, 180_000);
-
-  it('loads the architecture graph', () => {
-    expect(graph.graph.version).toBe(1);
-  });
-});
-`;
-}
-
-function ruleSpecSource(rule: (typeof RULES)[number]): string {
-  return `import { beforeAll, describe, it } from 'vitest';
-import { ${rule.helper} } from '@craft-ts/dev-tools';
-import { loadArchitectureGraph } from '../load-graph';
-
-describe('${rule.describe}', () => {
-  let graph: ReturnType<typeof loadArchitectureGraph>;
-
-  beforeAll(() => {
-    graph = loadArchitectureGraph();
-  }, 180_000);
-
-  it('${rule.it}', () => {
-    ${rule.call};
-  });
-});
-`;
-}
-
-function vitestConfig(context: ArchitectureContext): string {
-  if (context.nx) {
-    const cacheRel = posixRelative(
-      context.appRoot,
-      join(
-        context.workspaceRoot,
-        'node_modules',
-        '.vite',
-        `${context.projectName}-architecture`,
-      ),
-    );
-    return `/// <reference types="vitest" />
-import { defineConfig } from 'vite';
-
-export default defineConfig(() => ({
-  root: import.meta.dirname,
-  cacheDir: ${JSON.stringify(cacheRel)},
-  plugins: [],
-  resolve: {
-    tsconfigPaths: true,
-  },
-  test: {
-    name: ${JSON.stringify(`${context.projectName}-architecture`)},
-    watch: false,
-    globals: true,
-    environment: 'node',
-    testTimeout: 180_000,
-    hookTimeout: 180_000,
-    include: ['architecture/**/*.spec.ts'],
-  },
-}));
-`;
-  }
-  return `/// <reference types="vitest" />
-import { defineConfig } from 'vite';
-
-export default defineConfig(() => ({
-  root: import.meta.dirname,
-  cacheDir: ${JSON.stringify(`node_modules/.vite/${context.projectName}-architecture`)},
-  test: {
-    name: ${JSON.stringify(`${context.projectName}-architecture`)},
-    watch: false,
-    globals: true,
-    environment: 'node',
-    testTimeout: 180_000,
-    hookTimeout: 180_000,
-    include: ['architecture/**/*.spec.ts'],
-  },
-}));
-`;
-}
-
-function defaultTsConfig(rootDir: string): string {
-  for (const name of ['tsconfig.app.json', 'tsconfig.json']) {
-    const candidate = join(rootDir, name);
-    if (existsSync(candidate)) return candidate;
-    const parent = join(dirname(rootDir), name);
-    if (existsSync(parent)) return parent;
-  }
-  return join(rootDir, 'tsconfig.json');
-}
-
-function findWorkspaceRoot(appRoot: string): string {
-  let current = appRoot;
-  while (true) {
-    if (
-      existsSync(join(current, 'nx.json')) ||
-      existsSync(join(current, 'angular.json'))
-    ) {
-      return current;
-    }
-    const parent = dirname(current);
-    if (parent === current) return appRoot;
-    current = parent;
-  }
-}
-
-async function readProjectName(appRoot: string, nx: boolean): Promise<string> {
-  if (nx) {
-    try {
-      const project = JSON.parse(
-        await readFile(join(appRoot, 'project.json'), 'utf8'),
-      ) as { name?: string };
-      if (project.name) return sanitizeName(project.name);
-    } catch {
-      /* fall through */
-    }
-  }
-  try {
-    const pkg = JSON.parse(
-      await readFile(join(appRoot, 'package.json'), 'utf8'),
-    ) as { name?: string };
-    if (pkg.name) return sanitizeName(pkg.name);
-  } catch {
-    /* fall through */
-  }
-  return sanitizeName(appRoot.split(/[\\/]/).at(-1) ?? 'app');
-}
-
-function sanitizeName(name: string): string {
-  return name.replace(/^@.*\//, '').replace(/[^a-zA-Z0-9._-]/g, '-');
-}
-
-function posixRelative(from: string, to: string): string {
-  const value = relative(from, to).split('\\').join('/');
-  return value === '' ? '.' : value;
-}
-
-async function patchNxProject(context: ArchitectureContext): Promise<void> {
-  const projectPath = join(context.appRoot, 'project.json');
-  if (!existsSync(projectPath)) return;
-  const project = JSON.parse(await readFile(projectPath, 'utf8')) as {
-    targets?: Record<string, unknown>;
-  };
-  const cwd = posixRelative(context.workspaceRoot, context.appRoot);
-  project.targets = {
-    ...project.targets,
-    architecture: {
-      executor: 'nx:run-commands',
-      options: {
-        command: 'npx vitest run --config vitest.architecture.config.ts',
-        cwd,
-      },
-      inputs: [
-        '{projectRoot}/src/**/*.ts',
-        '{projectRoot}/architecture/**/*.ts',
-        '{projectRoot}/tsconfig.graph.json',
-        '{projectRoot}/tsconfig.architecture.json',
-      ],
-      cache: true,
-    },
-    'typecheck-architecture': {
-      executor: 'nx:run-commands',
-      options: {
-        cwd,
-        command: 'tsc -p tsconfig.architecture.json --noEmit --pretty false',
-      },
-      inputs: [
-        '{projectRoot}/tsconfig.json',
-        '{projectRoot}/tsconfig.architecture.json',
-        '{projectRoot}/architecture/**/*.ts',
-      ],
-      cache: true,
-    },
-  };
-  await writeFile(projectPath, `${JSON.stringify(project, null, 2)}\n`, 'utf8');
-}
-
-async function patchPackageJson(
-  packagePath: string,
-  context: ArchitectureContext,
-): Promise<void> {
-  const pkg = JSON.parse(await readFile(packagePath, 'utf8')) as {
-    scripts?: Record<string, string>;
-  };
-  const fromPkg = dirname(packagePath);
-  const vitestConfig = posixRelative(
-    fromPkg,
-    join(context.appRoot, 'vitest.architecture.config.ts'),
-  );
-  const architectureTsconfig = posixRelative(
-    fromPkg,
-    join(context.appRoot, 'tsconfig.architecture.json'),
-  );
-  pkg.scripts = {
-    ...pkg.scripts,
-    architecture: `vitest run --config ${vitestConfig}`,
-    'typecheck-architecture': `tsc -p ${architectureTsconfig} --noEmit --pretty false`,
-  };
-  await writeFile(packagePath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
-}
-
-async function scaffoldMatches(
-  context: ArchitectureContext,
-  files: Record<string, string>,
-): Promise<boolean> {
-  for (const [relativePath, contents] of Object.entries(files)) {
-    const fullPath = join(context.appRoot, relativePath);
-    if (!existsSync(fullPath)) return false;
-    if (
-      relativePath === 'architecture/catalog.ts' ||
-      relativePath === 'architecture/architecture.spec.ts'
-    ) {
-      continue;
-    }
-    const actual = await readFile(fullPath, 'utf8');
-    if (normalize(actual) !== normalize(contents)) return false;
-  }
-  if (context.nx) {
-    const projectPath = join(context.appRoot, 'project.json');
-    if (!existsSync(projectPath)) return false;
-    const project = JSON.parse(await readFile(projectPath, 'utf8')) as {
-      targets?: Record<string, { options?: { command?: string } }>;
-    };
-    return Boolean(project.targets?.['architecture']?.options?.command);
-  }
-  const packagePath = findPackageJson(context.appRoot, context.workspaceRoot);
-  if (!packagePath) return false;
-  const pkg = JSON.parse(await readFile(packagePath, 'utf8')) as {
-    scripts?: Record<string, string>;
-  };
-  return pkg.scripts?.['architecture']?.includes('vitest.architecture.config.ts') === true;
-}
-
-function normalize(value: string): string {
-  return value.replace(/\r\n/g, '\n');
-}
-
-const ESLINT_CONFIG_NAMES = [
-  'eslint.config.js',
-  'eslint.config.mjs',
-  'eslint.config.cjs',
-  'eslint.config.ts',
-  'eslint.config.mts',
-  'eslint.config.cts',
-];
-
-async function patchTsconfigReferences(appRoot: string): Promise<void> {
-  const tsconfigPath = join(appRoot, 'tsconfig.json');
-  if (!existsSync(tsconfigPath)) return;
-  const text = await readFile(tsconfigPath, 'utf8');
-  let parsed: { references?: { path: string }[] };
-  try {
-    parsed = JSON.parse(text) as { references?: { path: string }[] };
-  } catch {
-    return;
-  }
-  const references = parsed.references ?? [];
-  if (references.some((ref) => ref.path === './tsconfig.architecture.json')) {
-    return;
-  }
-  parsed.references = [...references, { path: './tsconfig.architecture.json' }];
-  await writeFile(tsconfigPath, `${JSON.stringify(parsed, null, 2)}\n`, 'utf8');
-}
-
-async function patchEslintIgnore(
-  appRoot: string,
-  workspaceRoot: string,
-): Promise<void> {
-  const eslintPath = findEslintConfig(appRoot, workspaceRoot);
-  if (!eslintPath) return;
-  const text = await readFile(eslintPath, 'utf8');
-  if (text.includes('architecture/catalog.ts')) return;
-  let next = text;
-  if (/ignores:\s*\[/.test(next)) {
-    next = next.replace(
-      /ignores:\s*\[/,
-      "ignores: ['**/architecture/catalog.ts', ",
-    );
-  } else if (/export default\s*(?:defineConfig\s*\()?\[/.test(next)) {
-    next = next.replace(
-      /export default\s*(?:defineConfig\s*\()?\[/,
-      (match) => `${match}\n  { ignores: ['**/architecture/catalog.ts'] },`,
-    );
-  } else {
-    return;
-  }
-  await writeFile(eslintPath, next, 'utf8');
-}
-
-function findEslintConfig(
-  startDir: string,
-  stopDir: string,
-): string | undefined {
-  return findUpFile(startDir, ESLINT_CONFIG_NAMES, stopDir);
-}
-
-function findPackageJson(
-  startDir: string,
-  stopDir: string,
-): string | undefined {
-  return findUpFile(startDir, ['package.json'], stopDir);
-}
-
-function findUpFile(
-  startDir: string,
-  names: readonly string[],
-  stopDir: string,
-): string | undefined {
-  const stop = resolve(stopDir);
-  let current = resolve(startDir);
-  while (true) {
-    for (const name of names) {
-      const candidate = join(current, name);
-      if (existsSync(candidate)) return candidate;
-    }
-    if (current === stop) return undefined;
-    const parent = dirname(current);
-    if (parent === current) return undefined;
-    current = parent;
-  }
-}