@archora/core 1.1.0

package/src/analyzer/metrics.ts

@@ -0,0 +1,156 @@
+import type { Cycle, DependencyEdge, ModuleId, ModuleMetrics, ModuleNode } from './types';
+
+export interface ComputeMetricsInput {
+  modules: ModuleNode[];
+  edges: DependencyEdge[];
+  cycles: Cycle[];
+  entries: ModuleId[];
+}
+
+export function computeMetrics(input: ComputeMetricsInput): Record<ModuleId, ModuleMetrics> {
+  const { modules, edges, cycles, entries } = input;
+
+  const graphEdges = edges.filter((e) => e.kind !== 'type-only');
+  const ids = modules.map((m) => m.id);
+
+  const fanIn = new Map<ModuleId, number>();
+  const fanOut = new Map<ModuleId, number>();
+  for (const id of ids) {
+    fanIn.set(id, 0);
+    fanOut.set(id, 0);
+  }
+  for (const e of graphEdges) {
+    fanOut.set(e.from, (fanOut.get(e.from) ?? 0) + 1);
+    fanIn.set(e.to, (fanIn.get(e.to) ?? 0) + 1);
+  }
+
+  const inCycle = new Set<ModuleId>();
+  for (const c of cycles) {
+    if (c.length > 1 || c.severity === 'direct') {
+      for (const id of c.modules) inCycle.add(id);
+    }
+  }
+
+  const depths = computeDepths(ids, graphEdges, cycles, entries);
+
+  const result: Record<ModuleId, ModuleMetrics> = {};
+
+  let maxCoupling = 0;
+  const rawCoupling = new Map<ModuleId, number>();
+  for (const id of ids) {
+    const fi = fanIn.get(id) ?? 0;
+    const fo = fanOut.get(id) ?? 0;
+    const c = Math.log2(fi + 1) * Math.log2(fo + 1);
+    rawCoupling.set(id, c);
+    if (c > maxCoupling) maxCoupling = c;
+  }
+
+  let maxLoc = 0;
+  for (const m of modules) if (m.loc > maxLoc) maxLoc = m.loc;
+
+  for (const m of modules) {
+    const id = m.id;
+    const fi = fanIn.get(id) ?? 0;
+    const fo = fanOut.get(id) ?? 0;
+    const sum = fi + fo;
+    const instability = sum === 0 ? 0 : fo / sum;
+    const cycle = inCycle.has(id);
+    const coupling = maxCoupling === 0 ? 0 : (rawCoupling.get(id) ?? 0) / maxCoupling;
+    const sizeFactor = maxLoc === 0 ? 1 : 1 + Math.log2(1 + m.loc) / Math.log2(1 + maxLoc);
+    const hotness = coupling * (cycle ? 1.5 : 1) * sizeFactor;
+    result[id] = {
+      fanIn: fi,
+      fanOut: fo,
+      instability: round(instability),
+      depth: depths.get(id) ?? 0,
+      inCycle: cycle,
+      couplingScore: round(coupling),
+      hotnessScore: round(hotness),
+    };
+  }
+
+  return result;
+}
+
+function computeDepths(
+  ids: ModuleId[],
+  edges: DependencyEdge[],
+  cycles: Cycle[],
+  entries: ModuleId[],
+): Map<ModuleId, number> {
+  const compOf = new Map<ModuleId, number>();
+  let nextComp = 0;
+  for (const c of cycles) {
+    if (c.length > 1) {
+      for (const id of c.modules) compOf.set(id, nextComp);
+      nextComp++;
+    }
+  }
+  for (const id of ids) {
+    if (!compOf.has(id)) {
+      compOf.set(id, nextComp++);
+    }
+  }
+
+  const compEdges = new Map<number, Set<number>>();
+  for (let i = 0; i < nextComp; i++) compEdges.set(i, new Set());
+  for (const e of edges) {
+    const a = compOf.get(e.from);
+    const b = compOf.get(e.to);
+    if (a === undefined || b === undefined || a === b) continue;
+    compEdges.get(a)?.add(b);
+  }
+
+  const indeg = new Map<number, number>();
+  for (let i = 0; i < nextComp; i++) indeg.set(i, 0);
+  for (const [, outs] of compEdges) for (const o of outs) indeg.set(o, (indeg.get(o) ?? 0) + 1);
+
+  const order: number[] = [];
+  const queue: number[] = [];
+  for (const [c, d] of indeg) if (d === 0) queue.push(c);
+  while (queue.length) {
+    const c = queue.shift();
+    if (c === undefined) break;
+    order.push(c);
+    for (const o of compEdges.get(c) ?? []) {
+      const d = (indeg.get(o) ?? 0) - 1;
+      indeg.set(o, d);
+      if (d === 0) queue.push(o);
+    }
+  }
+
+  const dist = new Map<number, number>();
+  const entryComps = new Set<number>();
+  for (const id of entries) {
+    const c = compOf.get(id);
+    if (c !== undefined) entryComps.add(c);
+  }
+  if (entryComps.size === 0) {
+    for (let i = 0; i < nextComp; i++) if ((indeg.get(i) ?? 0) === 0) entryComps.add(i);
+  }
+  for (const c of entryComps) dist.set(c, 0);
+
+  for (const c of order) {
+    if (!dist.has(c)) continue;
+    const d = dist.get(c) ?? 0;
+    for (const o of compEdges.get(c) ?? []) {
+      const cur = dist.get(o);
+      if (cur === undefined || cur < d + 1) dist.set(o, d + 1);
+    }
+  }
+
+  const depthByModule = new Map<ModuleId, number>();
+  for (const id of ids) {
+    const c = compOf.get(id);
+    if (c === undefined) {
+      depthByModule.set(id, 0);
+      continue;
+    }
+    depthByModule.set(id, dist.get(c) ?? 0);
+  }
+  return depthByModule;
+}
+
+function round(x: number): number {
+  return Math.round(x * 1000) / 1000;
+}

package/src/analyzer/parsers/index.ts

@@ -0,0 +1,62 @@
+import type { ModuleLanguage, ParsedFile } from '../types';
+import type { Framework } from '../detect';
+import type { DynamicLoaderConfig } from '../../config/frontScopeConfig';
+import { createTsParser, type TsParser } from './tsParser';
+import { createVueParser, type VueParser } from './vueParser';
+import { createReactParser, type ReactParser } from './reactParser';
+import { createSvelteParser, type SvelteParser } from './svelteParser';
+
+export interface ParserRegistryOptions {
+  framework?: Framework;
+  dynamicLoaders?: DynamicLoaderConfig[];
+}
+
+export interface ParseFailure {
+  reason: 'unsupported-extension';
+}
+
+export interface ParserRegistry {
+  parse(input: { relPath: string; content: string }): ParsedFile | ParseFailure;
+}
+
+const TS_LANG_BY_EXT: Record<string, ModuleLanguage> = {
+  ts: 'ts',
+  tsx: 'ts',
+  js: 'js',
+  jsx: 'js',
+  mjs: 'js',
+  cjs: 'js',
+};
+
+export function createParserRegistry(options: ParserRegistryOptions = {}): ParserRegistry {
+  const tsParser: TsParser = createTsParser({
+    ...(options.dynamicLoaders ? { dynamicLoaders: options.dynamicLoaders } : {}),
+  });
+  const vueParser: VueParser = createVueParser(tsParser);
+  const reactParser: ReactParser = createReactParser(tsParser);
+  const svelteParser: SvelteParser = createSvelteParser(tsParser);
+  const isReactProject = options.framework === 'react' || options.framework === 'next';
+
+  return {
+    parse({ relPath, content }) {
+      const ext = extOf(relPath);
+      if (ext === 'vue') return vueParser.parse({ relPath, content });
+      if (ext === 'svelte') return svelteParser.parse({ relPath, content });
+      const lang = TS_LANG_BY_EXT[ext];
+      if (lang) {
+        if (isReactProject) return reactParser.parse({ relPath, content, language: lang });
+        return tsParser.parse({ relPath, content, language: lang });
+      }
+      return { reason: 'unsupported-extension' };
+    },
+  };
+}
+
+export function isParseFailure(result: ParsedFile | ParseFailure): result is ParseFailure {
+  return 'reason' in result;
+}
+
+function extOf(relPath: string): string {
+  const i = relPath.lastIndexOf('.');
+  return i === -1 ? '' : relPath.slice(i + 1).toLowerCase();
+}

package/src/analyzer/parsers/reactParser.ts

@@ -0,0 +1,24 @@
+import type { ParsedFile } from '../types';
+import type { TsParser, TsParseInput } from './tsParser';
+
+export interface ReactParseInput {
+  relPath: string;
+  content: string;
+  language: TsParseInput['language'];
+}
+
+export interface ReactParser {
+  parse(input: ReactParseInput): ParsedFile;
+}
+
+export function createReactParser(tsParser: TsParser): ReactParser {
+  return {
+    parse(input) {
+      return tsParser.parse({
+        relPath: input.relPath,
+        content: input.content,
+        language: input.language,
+      });
+    },
+  };
+}

package/src/analyzer/parsers/svelteParser.ts

@@ -0,0 +1,46 @@
+import type { ParsedFile } from '../types';
+import type { TsParser } from './tsParser';
+
+export interface SvelteParseInput {
+  relPath: string;
+  content: string;
+}
+
+export interface SvelteParser {
+  parse(input: SvelteParseInput): ParsedFile;
+}
+
+const SCRIPT_BLOCK_RE = /<\s*script\b[^>]*>([\s\S]*?)<\/\s*script\s*>/giu;
+
+export function createSvelteParser(tsParser: TsParser): SvelteParser {
+  return {
+    parse(input) {
+      const code = extractScripts(input.content);
+      const parsed = tsParser.parse({
+        relPath: input.relPath,
+        content: code,
+        language: 'ts',
+      });
+      return {
+        ...parsed,
+        loc: countLines(input.content),
+        language: 'svelte',
+      };
+    },
+  };
+}
+
+function extractScripts(content: string): string {
+  const blocks: string[] = [];
+  for (const m of content.matchAll(SCRIPT_BLOCK_RE)) {
+    if (m[1]) blocks.push(m[1]);
+  }
+  return blocks.join('\n');
+}
+
+function countLines(content: string): number {
+  if (content.length === 0) return 0;
+  let n = 1;
+  for (let i = 0; i < content.length; i++) if (content[i] === '\n') n++;
+  return n;
+}

package/src/analyzer/parsers/tsParser.ts

@@ -0,0 +1,364 @@
+import ts from 'typescript';
+import type { ModuleLanguage, ParsedFile, RawImport } from '../types';
+import type { DynamicLoaderConfig } from '../../config/frontScopeConfig';
+
+export interface TsParseInput {
+  relPath: string;
+  content: string;
+  language: ModuleLanguage;
+}
+
+export interface TsParser {
+  parse(input: TsParseInput): ParsedFile;
+}
+
+export interface TsParserOptions {
+  dynamicLoaders?: DynamicLoaderConfig[];
+}
+
+const SCRIPT_KIND_BY_EXT: Record<string, ts.ScriptKind> = {
+  ts: ts.ScriptKind.TS,
+  tsx: ts.ScriptKind.TSX,
+  js: ts.ScriptKind.JS,
+  jsx: ts.ScriptKind.JSX,
+  mjs: ts.ScriptKind.JS,
+  cjs: ts.ScriptKind.JS,
+};
+
+export function createTsParser(options: TsParserOptions = {}): TsParser {
+  const loaders = options.dynamicLoaders ?? [];
+  return {
+    parse(input: TsParseInput): ParsedFile {
+      const sf = ts.createSourceFile(
+        input.relPath,
+        input.content,
+        ts.ScriptTarget.Latest,
+        false,
+        scriptKindFor(input.relPath, input.language),
+      );
+
+      const imports: RawImport[] = [];
+      const exports = new Set<string>();
+      let hasDefineStore = false;
+
+      visit(
+        sf,
+        sf,
+        imports,
+        exports,
+        () => {
+          hasDefineStore = true;
+        },
+        loaders,
+      );
+
+      const directives = readDirectivePrologue(sf);
+
+      return {
+        relPath: input.relPath,
+        language: input.language,
+        loc: countLines(input.content),
+        imports,
+        exports: [...exports].sort(),
+        hasDefineStore: hasDefineStore || /\bdefineStore\s*\(/.test(input.content),
+        ...(directives.length > 0 ? { directives } : {}),
+      };
+    },
+  };
+}
+
+function scriptKindFor(relPath: string, language: ModuleLanguage): ts.ScriptKind {
+  if (language === 'vue') return ts.ScriptKind.TS;
+  const ext = relPath.slice(relPath.lastIndexOf('.') + 1).toLowerCase();
+  return SCRIPT_KIND_BY_EXT[ext] ?? ts.ScriptKind.TS;
+}
+
+function visit(
+  node: ts.Node,
+  sf: ts.SourceFile,
+  imports: RawImport[],
+  exports: Set<string>,
+  markDefineStore: () => void,
+  loaders: DynamicLoaderConfig[],
+): void {
+  if (ts.isImportDeclaration(node)) {
+    const spec = literalText(node.moduleSpecifier);
+    if (spec !== null) {
+      imports.push({ specifier: spec, kind: classifyImport(node) });
+    }
+    return;
+  }
+
+  if (ts.isExportDeclaration(node)) {
+    const spec = node.moduleSpecifier ? literalText(node.moduleSpecifier) : null;
+    if (spec !== null) {
+      imports.push({ specifier: spec, kind: node.isTypeOnly ? 'type-only' : 'static' });
+    }
+    if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+      for (const el of node.exportClause.elements) exports.add(el.name.text);
+    } else if (node.exportClause && ts.isNamespaceExport(node.exportClause)) {
+      exports.add(node.exportClause.name.text);
+    }
+    return;
+  }
+
+  if (
+    ts.isCallExpression(node) &&
+    node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+    node.arguments.length > 0
+  ) {
+    const arg = node.arguments[0];
+    if (arg) {
+      const spec = literalText(arg);
+      if (spec !== null) {
+        imports.push({ specifier: spec, kind: 'dynamic' });
+      } else {
+        // template-literal import() - keep the static prefix
+        // TODO: handle the dynamic tail too (e.g. via a pattern marker), so
+        // `./views/${name}.vue` resolves against actual files in ./views.
+        const prefix = staticPrefix(arg);
+        if (prefix !== null && prefix.length > 0) {
+          imports.push({ specifier: prefix, kind: 'dynamic', pattern: 'prefix' });
+        }
+      }
+    }
+  }
+
+  if (
+    ts.isCallExpression(node) &&
+    ts.isIdentifier(node.expression) &&
+    node.expression.text === 'defineStore'
+  ) {
+    markDefineStore();
+  }
+
+  // CommonJS require() -> static dep
+  if (
+    ts.isCallExpression(node) &&
+    ts.isIdentifier(node.expression) &&
+    node.expression.text === 'require' &&
+    node.arguments.length > 0
+  ) {
+    const arg = node.arguments[0];
+    if (arg) {
+      const spec = literalText(arg);
+      if (spec !== null) imports.push({ specifier: spec, kind: 'static' });
+    }
+  }
+
+  // user-defined dynamic loaders from .archora.json (match by ident name only)
+  if (
+    loaders.length > 0 &&
+    ts.isCallExpression(node) &&
+    ts.isIdentifier(node.expression) &&
+    node.arguments.length > 0
+  ) {
+    const fnName = node.expression.text;
+    for (const loader of loaders) {
+      if (loader.name !== fnName) continue;
+      const idx = loader.argIndex ?? 0;
+      const arg = node.arguments[idx];
+      if (!arg) continue;
+      const literal = literalText(arg);
+      if (literal === null) continue;
+      const resolved = loader.resolveAs.replace(/\{0\}/gu, literal);
+      imports.push({ specifier: resolved, kind: 'dynamic' });
+    }
+  }
+
+  // import.meta.glob / globEager - accepts a string or array; both eager and lazy modes count
+  if (ts.isCallExpression(node) && isImportMetaGlob(node.expression) && node.arguments.length > 0) {
+    const first = node.arguments[0];
+    if (first) {
+      const patterns = collectGlobPatterns(first);
+      const globOptions = collectGlobOptions(
+        node.arguments[1],
+        isImportMetaGlobEager(node.expression),
+      );
+      for (const p of patterns) {
+        imports.push({
+          specifier: p,
+          kind: 'dynamic',
+          pattern: 'glob',
+          confidence: globOptions.eager ? 'medium' : 'low',
+          approximate: true,
+          globEager: globOptions.eager,
+          ...(globOptions.importName ? { globImport: globOptions.importName } : {}),
+        });
+      }
+    }
+  }
+
+  if (ts.isVariableStatement(node) && hasExportModifier(node)) {
+    for (const decl of node.declarationList.declarations) collectBindingNames(decl.name, exports);
+  } else if (
+    (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) &&
+    hasExportModifier(node)
+  ) {
+    if (node.name) exports.add(node.name.text);
+    else if (hasDefaultModifier(node)) exports.add('default');
+  } else if (
+    (ts.isInterfaceDeclaration(node) ||
+      ts.isTypeAliasDeclaration(node) ||
+      ts.isEnumDeclaration(node)) &&
+    hasExportModifier(node)
+  ) {
+    exports.add(node.name.text);
+  } else if (ts.isExportAssignment(node)) {
+    exports.add('default');
+  }
+
+  ts.forEachChild(node, (child) => visit(child, sf, imports, exports, markDefineStore, loaders));
+}
+
+function literalText(node: ts.Node): string | null {
+  if (ts.isStringLiteralLike(node)) return node.text;
+  return null;
+}
+
+// matches `import.meta.glob`, `import.meta.globEager`, and bracket variants
+function isImportMetaGlob(expr: ts.Expression): boolean {
+  const name = importMetaPropertyName(expr);
+  return name === 'glob' || name === 'globEager';
+}
+
+function isImportMetaGlobEager(expr: ts.Expression): boolean {
+  return importMetaPropertyName(expr) === 'globEager';
+}
+
+function importMetaPropertyName(expr: ts.Expression): string | null {
+  if (!ts.isPropertyAccessExpression(expr) && !ts.isElementAccessExpression(expr)) return null;
+  const obj = expr.expression;
+  if (!ts.isMetaProperty(obj)) return null;
+  if (obj.keywordToken !== ts.SyntaxKind.ImportKeyword) return null;
+  if (obj.name.text !== 'meta') return null;
+  if (ts.isPropertyAccessExpression(expr)) return expr.name.text;
+  return literalText(expr.argumentExpression);
+}
+
+function collectGlobPatterns(node: ts.Node): string[] {
+  const out: string[] = [];
+  if (ts.isStringLiteralLike(node)) {
+    out.push(node.text);
+  } else if (ts.isArrayLiteralExpression(node)) {
+    for (const el of node.elements) {
+      const t = literalText(el);
+      if (t !== null) out.push(t);
+    }
+  }
+  return out;
+}
+
+function collectGlobOptions(
+  node: ts.Node | undefined,
+  legacyEager = false,
+): { eager: boolean; importName?: string } {
+  if (!node || !ts.isObjectLiteralExpression(node)) return { eager: legacyEager };
+  let eager = legacyEager;
+  let importName: string | undefined;
+  for (const prop of node.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue;
+    const key = propertyNameText(prop.name);
+    if (key === 'eager' && prop.initializer.kind === ts.SyntaxKind.TrueKeyword) {
+      eager = true;
+    } else if (key === 'import') {
+      const literal = literalText(prop.initializer);
+      if (literal !== null) importName = literal;
+    }
+  }
+  return importName ? { eager, importName } : { eager };
+}
+
+function propertyNameText(name: ts.PropertyName): string | null {
+  if (ts.isIdentifier(name) || ts.isStringLiteralLike(name)) return name.text;
+  return null;
+}
+
+// extracts the static prefix from `./mfes/${name}` or `'./mfes/' + name`.
+// buildGraph uses it for prefix expansion of MFE-style loaders.
+function staticPrefix(node: ts.Node): string | null {
+  if (ts.isTemplateExpression(node)) {
+    return node.head.text;
+  }
+  if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+    const left = staticPrefix(node.left);
+    if (left !== null) return left;
+    return null;
+  }
+  if (ts.isStringLiteralLike(node)) {
+    return node.text;
+  }
+  return null;
+}
+
+function classifyImport(node: ts.ImportDeclaration): RawImport['kind'] {
+  if (node.importClause?.isTypeOnly) return 'type-only';
+  const clause = node.importClause;
+  if (!clause) return 'side-effect';
+  const namedBindings = clause.namedBindings;
+  if (
+    namedBindings &&
+    ts.isNamedImports(namedBindings) &&
+    !clause.name &&
+    namedBindings.elements.length > 0 &&
+    namedBindings.elements.every((el) => el.isTypeOnly)
+  ) {
+    return 'type-only';
+  }
+  return 'static';
+}
+
+function hasExportModifier(node: ts.Node): boolean {
+  return ts.canHaveModifiers(node)
+    ? !!ts.getModifiers(node)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+    : false;
+}
+
+function hasDefaultModifier(node: ts.Node): boolean {
+  return ts.canHaveModifiers(node)
+    ? !!ts.getModifiers(node)?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)
+    : false;
+}
+
+function collectBindingNames(name: ts.BindingName, out: Set<string>): void {
+  if (ts.isIdentifier(name)) {
+    out.add(name.text);
+    return;
+  }
+  if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name)) {
+    for (const el of name.elements) {
+      if (ts.isBindingElement(el)) collectBindingNames(el.name, out);
+    }
+  }
+}
+
+// Directive prologue: a sequence of plain string-literal expression statements
+// at the top of the file (and the top of each function body, but for our
+// purposes the top of the file is enough). Stops at the first non-directive.
+function readDirectivePrologue(sf: ts.SourceFile): ('use server' | 'use client')[] {
+  const out: ('use server' | 'use client')[] = [];
+  for (const stmt of sf.statements) {
+    if (
+      ts.isExpressionStatement(stmt) &&
+      ts.isStringLiteralLike(stmt.expression) &&
+      !stmt.expression.getText(sf).startsWith('`')
+    ) {
+      const text = stmt.expression.text;
+      if (text === 'use server' || text === 'use client') {
+        out.push(text);
+        continue;
+      }
+      // Other prologue strings (e.g. 'use strict') are tolerated.
+      continue;
+    }
+    break;
+  }
+  return out;
+}
+
+function countLines(content: string): number {
+  if (content.length === 0) return 0;
+  let n = 1;
+  for (let i = 0; i < content.length; i++) if (content[i] === '\n') n++;
+  return n;
+}