@archora/core 1.1.0

package/src/analyzer/__tests__/vueAutoImport.test.ts

@@ -0,0 +1,177 @@
+import { describe, it, expect } from 'vitest';
+import { createParserRegistry, isParseFailure } from '../parsers';
+import { analyze } from '../index';
+import { createInMemoryFileSource } from '../sources/inMemoryFileSource';
+import type { ParsedFile } from '../types';
+
+const parseVue = (relPath: string, content: string): ParsedFile => {
+  const registry = createParserRegistry({ framework: 'vue' });
+  const r = registry.parse({ relPath, content });
+  if (isParseFailure(r)) throw new Error(`parse failed: ${r.reason}`);
+  return r;
+};
+
+describe('vueParser: templateRefs extraction', () => {
+  it('extracts PascalCase component tags from <template>', () => {
+    const sfc = `<script setup lang="ts">
+const x = 1;
+</script>
+<template>
+  <AppHeader />
+  <div><MyButton>click</MyButton></div>
+</template>`;
+    const file = parseVue('App.vue', sfc);
+    expect(file.templateRefs).toEqual(expect.arrayContaining(['AppHeader', 'MyButton']));
+  });
+
+  it('normalizes kebab-case tags to PascalCase', () => {
+    const sfc = `<script setup lang="ts"></script>
+<template>
+  <my-fancy-button />
+</template>`;
+    const file = parseVue('A.vue', sfc);
+    expect(file.templateRefs).toContain('MyFancyButton');
+  });
+
+  it('excludes Vue / Vue Router built-in tags', () => {
+    const sfc = `<script setup lang="ts"></script>
+<template>
+  <Transition><div /></Transition>
+  <KeepAlive><RouterView /></KeepAlive>
+  <Suspense><Teleport to="body"><RouterLink to="/x">x</RouterLink></Teleport></Suspense>
+  <NuxtLink to="/y" />
+  <ClientOnly />
+  <UserCard />
+</template>`;
+    const file = parseVue('A.vue', sfc);
+    expect(file.templateRefs).toEqual(['UserCard']);
+  });
+
+  it('excludes plain HTML elements (compiler-sfc tagType filter)', () => {
+    const sfc = `<script setup lang="ts"></script>
+<template>
+  <div><span><button>x</button></span></div>
+  <header><nav><ul><li>x</li></ul></nav></header>
+</template>`;
+    const file = parseVue('A.vue', sfc);
+    expect(file.templateRefs ?? []).toEqual([]);
+  });
+
+  it('omits templateRefs entirely on .vue files without a template', () => {
+    const sfc = `<script setup lang="ts">
+export const x = 1;
+</script>`;
+    const file = parseVue('A.vue', sfc);
+    expect(file.templateRefs).toBeUndefined();
+  });
+
+  it('deduplicates multiple usages of the same tag', () => {
+    const sfc = `<script setup lang="ts"></script>
+<template>
+  <UserCard /><UserCard /><UserCard />
+</template>`;
+    const file = parseVue('A.vue', sfc);
+    expect(file.templateRefs).toEqual(['UserCard']);
+  });
+
+  it('walks nested children', () => {
+    const sfc = `<script setup lang="ts"></script>
+<template>
+  <div>
+    <section>
+      <article>
+        <DeepCard />
+      </article>
+    </section>
+  </div>
+</template>`;
+    const file = parseVue('A.vue', sfc);
+    expect(file.templateRefs).toContain('DeepCard');
+  });
+});
+
+describe('buildGraph: unplugin-vue-components auto-import resolution', () => {
+  it('emits auto-import edges for src/components/*.vue referenced only in template', async () => {
+    const src = createInMemoryFileSource('/p', {
+      'package.json': JSON.stringify({ dependencies: { vue: '^3.0.0' } }),
+      'tsconfig.json': '{}',
+      'src/main.ts': `import App from './App.vue';
+const app = App;`,
+      'src/App.vue': `<script setup lang="ts"></script>
+<template><AppHeader /><AppFooter /></template>`,
+      'src/components/AppHeader.vue': `<template><header /></template>`,
+      'src/components/AppFooter.vue': `<template><footer /></template>`,
+    });
+    const result = await analyze(src);
+    const fromApp = result.edges.filter((e) => e.from === 'src/App.vue');
+    const autoImports = fromApp.filter((e) => e.kind === 'auto-import');
+    expect(autoImports.map((e) => ({ to: e.to, specifier: e.specifier }))).toEqual(
+      expect.arrayContaining([
+        { to: 'src/components/AppHeader.vue', specifier: 'AppHeader' },
+        { to: 'src/components/AppFooter.vue', specifier: 'AppFooter' },
+      ]),
+    );
+  });
+
+  it('does NOT emit auto-import edge when the script already imports the component', async () => {
+    const src = createInMemoryFileSource('/p', {
+      'package.json': JSON.stringify({ dependencies: { vue: '^3.0.0' } }),
+      'tsconfig.json': '{}',
+      'src/App.vue': `<script setup lang="ts">
+import AppHeader from './components/AppHeader.vue';
+</script>
+<template><AppHeader /></template>`,
+      'src/components/AppHeader.vue': `<template><header /></template>`,
+    });
+    const result = await analyze(src);
+    const edges = result.edges.filter(
+      (e) => e.from === 'src/App.vue' && e.to === 'src/components/AppHeader.vue',
+    );
+    expect(edges).toHaveLength(1);
+    expect(edges[0]?.kind).toBe('static');
+  });
+
+  it('does NOT match components outside src/components/ (default unplugin convention)', async () => {
+    const src = createInMemoryFileSource('/p', {
+      'package.json': JSON.stringify({ dependencies: { vue: '^3.0.0' } }),
+      'tsconfig.json': '{}',
+      'src/App.vue': `<script setup lang="ts"></script>
+<template><HomeView /></template>`,
+      'src/views/HomeView.vue': `<template><main /></template>`,
+    });
+    const result = await analyze(src);
+    const autoImports = result.edges.filter((e) => e.kind === 'auto-import');
+    expect(autoImports).toEqual([]);
+  });
+
+  it('does not emit a self-edge when a component template references itself', async () => {
+    const src = createInMemoryFileSource('/p', {
+      'package.json': JSON.stringify({ dependencies: { vue: '^3.0.0' } }),
+      'tsconfig.json': '{}',
+      'src/components/Tree.vue': `<script setup lang="ts">
+defineProps<{ depth: number }>();
+</script>
+<template><div><Tree v-if="depth" :depth="depth - 1" /></div></template>`,
+    });
+    const result = await analyze(src);
+    const selfEdges = result.edges.filter(
+      (e) => e.from === 'src/components/Tree.vue' && e.to === 'src/components/Tree.vue',
+    );
+    expect(selfEdges).toEqual([]);
+  });
+
+  it('matches kebab-case template usage to the PascalCase file in registry', async () => {
+    const src = createInMemoryFileSource('/p', {
+      'package.json': JSON.stringify({ dependencies: { vue: '^3.0.0' } }),
+      'tsconfig.json': '{}',
+      'src/App.vue': `<script setup lang="ts"></script>
+<template><my-button /></template>`,
+      'src/components/MyButton.vue': `<template><button /></template>`,
+    });
+    const result = await analyze(src);
+    const autoImports = result.edges.filter(
+      (e) => e.from === 'src/App.vue' && e.kind === 'auto-import',
+    );
+    expect(autoImports.map((e) => e.to)).toEqual(['src/components/MyButton.vue']);
+  });
+});

package/src/analyzer/archDebt.ts

@@ -0,0 +1,68 @@
+import type { ArchDebt, Cycle, LayerViolation, ModuleMetrics, ModuleNode } from './types';
+
+interface Inputs {
+  modules: ModuleNode[];
+  cycles: Cycle[];
+  layerViolations: LayerViolation[];
+  metrics: Record<string, ModuleMetrics>;
+  hotZoneCount: number;
+}
+
+// composite arch-debt 0..100 (higher = worse).
+// weights: cycles 35 / layers 30 / coupling 20 / hot zones 15. each saturates.
+export function computeArchDebt(inputs: Inputs): ArchDebt {
+  const realModules = inputs.modules.filter((m) => !m.isInfra);
+  const moduleCount = Math.max(1, realModules.length);
+
+  const cycleWeight = inputs.cycles.reduce((acc, c) => acc + (c.severity === 'direct' ? 2 : 1), 0);
+  const cycleScore = saturate(cycleWeight / Math.max(1, moduleCount * 0.05));
+
+  const violationWeight = inputs.layerViolations.reduce(
+    (acc, v) => acc + (v.severity === 'error' ? 3 : 1),
+    0,
+  );
+  const layerScore = saturate(violationWeight / Math.max(1, moduleCount * 0.03));
+
+  const hotScore = saturate((inputs.hotZoneCount * 10) / moduleCount);
+
+  let instSum = 0;
+  let instCount = 0;
+  for (const m of realModules) {
+    const metrics = inputs.metrics[m.id];
+    if (!metrics) continue;
+    instSum += metrics.instability;
+    instCount++;
+  }
+  const couplingScore = instCount > 0 ? instSum / instCount : 0;
+
+  const score = clamp(
+    100 * (cycleScore * 0.35 + layerScore * 0.3 + hotScore * 0.15 + couplingScore * 0.2),
+  );
+
+  return {
+    score: Math.round(score),
+    grade: gradeOf(score),
+    breakdown: {
+      cycles: Math.round(cycleScore * 100),
+      layerViolations: Math.round(layerScore * 100),
+      hotZones: Math.round(hotScore * 100),
+      coupling: Math.round(couplingScore * 100),
+    },
+  };
+}
+
+function saturate(x: number): number {
+  return 1 - 1 / (1 + Math.max(0, x));
+}
+
+function clamp(x: number): number {
+  return Math.max(0, Math.min(100, x));
+}
+
+function gradeOf(score: number): ArchDebt['grade'] {
+  if (score < 15) return 'A';
+  if (score < 30) return 'B';
+  if (score < 50) return 'C';
+  if (score < 70) return 'D';
+  return 'F';
+}

package/src/analyzer/asyncLifecycleRisk.ts

@@ -0,0 +1,234 @@
+import ts from 'typescript';
+import type { FileSource } from './fileSource';
+import type { AsyncLifecycleRiskFinding, DetectedFramework, ModuleNode } from './types';
+
+export interface DetectAsyncLifecycleRisksInput {
+  source: FileSource;
+  modules: readonly ModuleNode[];
+  framework: DetectedFramework;
+}
+
+interface RiskContext {
+  module: ModuleNode;
+  framework: DetectedFramework;
+  sourceFile: ts.SourceFile;
+}
+
+export async function detectAsyncLifecycleRisks(
+  input: DetectAsyncLifecycleRisksInput,
+): Promise<AsyncLifecycleRiskFinding[]> {
+  const findings: AsyncLifecycleRiskFinding[] = [];
+  for (const module of input.modules) {
+    if (module.runtime === 'server') continue;
+    const code = await readSource(input.source, module.id);
+    if (code === null) continue;
+    const script = scriptContent(module.id, code);
+    if (script.trim().length === 0) continue;
+    const sourceFile = ts.createSourceFile(
+      module.id,
+      script,
+      ts.ScriptTarget.Latest,
+      false,
+      scriptKindFor(module.id),
+    );
+    const context = {
+      module,
+      framework: input.framework,
+      sourceFile,
+    };
+    findings.push(...detectInModule(context));
+  }
+  return dedupeFindings(findings);
+}
+
+function detectInModule(context: RiskContext): AsyncLifecycleRiskFinding[] {
+  if (context.framework === 'react' || context.framework === 'next') {
+    return detectLifecycleCall(context, 'useEffect', 'returned cleanup');
+  }
+  if (context.framework === 'vue' || context.framework === 'nuxt') {
+    const cleanupRoots = collectLifecycleCleanups(context.sourceFile, 'onUnmounted');
+    return detectLifecycleCall(context, 'onMounted', 'onUnmounted cleanup', cleanupRoots);
+  }
+  if (context.framework === 'svelte') {
+    return detectLifecycleCall(context, 'onMount', 'returned cleanup');
+  }
+  return [];
+}
+
+function detectLifecycleCall(
+  context: RiskContext,
+  lifecycleName: string,
+  cleanupLabel: string,
+  externalCleanupRoots: readonly ts.Node[] = [],
+): AsyncLifecycleRiskFinding[] {
+  const findings: AsyncLifecycleRiskFinding[] = [];
+  visit(context.sourceFile, (node) => {
+    if (!ts.isCallExpression(node) || !isIdentifierCall(node, lifecycleName)) return;
+    const callback = node.arguments[0];
+    if (!callback || !isFunctionLike(callback)) return;
+    const body = callback.body;
+    if (!ts.isBlock(body)) return;
+    if (!hasAsyncWork(body)) return;
+    if (hasAbortOrStaleGuard(body, externalCleanupRoots)) return;
+    findings.push(buildFinding(context, body, cleanupLabel));
+  });
+  return findings;
+}
+
+function buildFinding(
+  context: RiskContext,
+  node: ts.Node,
+  cleanupLabel: string,
+): AsyncLifecycleRiskFinding {
+  const line =
+    context.sourceFile.getLineAndCharacterOfPosition(node.getStart(context.sourceFile)).line + 1;
+  return {
+    id: `async-lifecycle:async-effect-cleanup:${context.module.id}:${line}`,
+    kind: 'async-effect-cleanup',
+    moduleId: context.module.id,
+    framework: context.framework,
+    severity: 'medium',
+    confidence: 'high',
+    evidence: [
+      {
+        message: `async lifecycle work has no visible abort, stale guard, or ${cleanupLabel}`,
+        line,
+        asyncSource: 'fetch',
+        expectedGuard: 'AbortController or stale guard cleanup',
+      },
+    ],
+    remediation:
+      'Add AbortController, a stale-result guard, or lifecycle cleanup before updating state.',
+  };
+}
+
+function hasAsyncWork(root: ts.Node): boolean {
+  return hasNode(root, (node) => {
+    if (ts.isAwaitExpression(node)) return true;
+    if (!ts.isCallExpression(node)) return false;
+    const name = callName(node.expression);
+    return name === 'fetch' || name === 'then' || name === 'catch' || name === 'finally';
+  });
+}
+
+function hasAbortOrStaleGuard(body: ts.Block, externalCleanupRoots: readonly ts.Node[]): boolean {
+  const roots = [body, returnedCleanup(body), ...externalCleanupRoots].filter(
+    (node): node is ts.Node => Boolean(node),
+  );
+  return (
+    roots.some((root) =>
+      hasNode(root, (node) => {
+        if (ts.isNewExpression(node) && callName(node.expression) === 'AbortController') {
+          return true;
+        }
+        if (!ts.isCallExpression(node)) return false;
+        const name = callName(node.expression);
+        return name === 'abort' || name === 'cancel' || name === 'unsubscribe' || name === 'stop';
+      }),
+    ) || hasStaleGuard(body)
+  );
+}
+
+function hasStaleGuard(root: ts.Node): boolean {
+  return hasNode(root, (node) => {
+    if (!ts.isIdentifier(node)) return false;
+    return /^(cancelled|canceled|stale|ignore|ignored|mounted|isMounted)$/u.test(node.text);
+  });
+}
+
+function returnedCleanup(block: ts.Block): ts.Node | undefined {
+  for (const statement of block.statements) {
+    if (!ts.isReturnStatement(statement) || !statement.expression) continue;
+    return statement.expression;
+  }
+  return undefined;
+}
+
+function collectLifecycleCleanups(sourceFile: ts.SourceFile, name: string): ts.Node[] {
+  const nodes: ts.Node[] = [];
+  visit(sourceFile, (node) => {
+    if (!ts.isCallExpression(node) || !isIdentifierCall(node, name)) return;
+    const callback = node.arguments[0];
+    if (callback && isFunctionLike(callback)) nodes.push(callback.body);
+  });
+  return nodes;
+}
+
+function visit(node: ts.Node, cb: (node: ts.Node) => void): void {
+  cb(node);
+  ts.forEachChild(node, (child) => visit(child, cb));
+}
+
+function hasNode(root: ts.Node, predicate: (node: ts.Node) => boolean): boolean {
+  let found = false;
+  visit(root, (node) => {
+    if (!found && predicate(node)) found = true;
+  });
+  return found;
+}
+
+function isFunctionLike(node: ts.Node): node is ts.ArrowFunction | ts.FunctionExpression {
+  return ts.isArrowFunction(node) || ts.isFunctionExpression(node);
+}
+
+function isIdentifierCall(node: ts.CallExpression, name: string): boolean {
+  return ts.isIdentifier(node.expression) && node.expression.text === name;
+}
+
+function callName(expression: ts.Expression): string | null {
+  if (ts.isIdentifier(expression)) return expression.text;
+  if (ts.isPropertyAccessExpression(expression)) return expression.name.text;
+  return null;
+}
+
+function dedupeFindings(
+  findings: readonly AsyncLifecycleRiskFinding[],
+): AsyncLifecycleRiskFinding[] {
+  const seen = new Set<string>();
+  const out: AsyncLifecycleRiskFinding[] = [];
+  for (const finding of findings) {
+    if (seen.has(finding.id)) continue;
+    seen.add(finding.id);
+    out.push(finding);
+  }
+  return out;
+}
+
+async function readSource(source: FileSource, moduleId: string): Promise<string | null> {
+  try {
+    return await source.read(moduleId);
+  } catch {
+    return null;
+  }
+}
+
+function scriptContent(moduleId: string, content: string): string {
+  if (moduleId.endsWith('.vue') || moduleId.endsWith('.svelte')) {
+    const blocks: string[] = [];
+    const lower = content.toLowerCase();
+    let offset = 0;
+    while (offset < content.length) {
+      const openStart = lower.indexOf('<script', offset);
+      if (openStart === -1) break;
+      const openEnd = lower.indexOf('>', openStart + '<script'.length);
+      if (openEnd === -1) break;
+      const closeStart = lower.indexOf('</script', openEnd + 1);
+      if (closeStart === -1) break;
+      const closeEnd = lower.indexOf('>', closeStart + '</script'.length);
+      const block = content.slice(openEnd + 1, closeStart);
+      if (block) blocks.push(block);
+      offset = closeEnd === -1 ? closeStart + '</script'.length : closeEnd + 1;
+    }
+    return blocks.join('\n');
+  }
+  return content;
+}
+
+function scriptKindFor(moduleId: string): ts.ScriptKind {
+  if (moduleId.endsWith('.tsx')) return ts.ScriptKind.TSX;
+  if (moduleId.endsWith('.jsx')) return ts.ScriptKind.JSX;
+  if (moduleId.endsWith('.js') || moduleId.endsWith('.mjs') || moduleId.endsWith('.cjs')) {
+    return ts.ScriptKind.JS;
+  }
+  return ts.ScriptKind.TS;
+}