@archora/core 1.1.0

package/src/analyzer/sources/browserFsAccessFileSource.ts

@@ -0,0 +1,132 @@
+import ignore, { type Ignore } from 'ignore';
+import type { FileSource } from '../fileSource';
+import { ALWAYS_SKIP_DIRS, TEST_LIKE_DIRS } from '../discover';
+
+const SUPPORTED_EXT = new Set(['.ts', '.tsx', '.js', '.jsx', '.vue', '.svelte', '.mjs', '.cjs']);
+
+export interface BrowserFsAccessFileSourceOptions {
+  rootHandle: FileSystemDirectoryHandle;
+  rootName?: string;
+  onProgress?: (visited: number) => void;
+  /** Если true (по умолчанию) - не заходим в тест/storybook/cypress/playwright директории. */
+  skipTestLikeDirs?: boolean;
+  /** Read `.gitignore` from root and filter the listing. Default: true. */
+  respectGitignore?: boolean;
+}
+
+async function loadRootGitignore(root: FileSystemDirectoryHandle): Promise<Ignore> {
+  const ig = ignore();
+  try {
+    const handle = await root.getFileHandle('.gitignore');
+    ig.add(await (await handle.getFile()).text());
+  } catch {
+    // No .gitignore at root.
+  }
+  return ig;
+}
+
+export async function createBrowserFsAccessFileSource(
+  options: BrowserFsAccessFileSourceOptions,
+): Promise<FileSource> {
+  const {
+    rootHandle,
+    rootName = rootHandle.name,
+    onProgress,
+    skipTestLikeDirs = true,
+    respectGitignore = true,
+  } = options;
+  const fileHandles = new Map<string, FileSystemFileHandle>();
+  const ig = respectGitignore ? await loadRootGitignore(rootHandle) : ignore();
+  let listed = false;
+
+  async function ensureListed(): Promise<void> {
+    if (listed) return;
+    let visited = 0;
+    await walk(
+      rootHandle,
+      '',
+      fileHandles,
+      () => {
+        visited++;
+        if (visited % 50 === 0) onProgress?.(visited);
+      },
+      skipTestLikeDirs,
+      ig,
+    );
+    onProgress?.(visited);
+    listed = true;
+  }
+
+  return {
+    rootPath: rootName,
+    async list(): Promise<string[]> {
+      await ensureListed();
+      return [...fileHandles.keys()].sort();
+    },
+    async read(rel: string): Promise<string> {
+      // cache is extension-filtered, so config files need a fallback lookup
+      await ensureListed();
+      const cached = fileHandles.get(rel);
+      if (cached) return (await cached.getFile()).text();
+      const handle = await resolveFileHandle(rootHandle, rel);
+      if (!handle) throw new Error(`File not found: ${rel}`);
+      return (await handle.getFile()).text();
+    },
+    async exists(rel: string): Promise<boolean> {
+      await ensureListed();
+      if (fileHandles.has(rel)) return true;
+      return (await resolveFileHandle(rootHandle, rel)) !== null;
+    },
+  };
+}
+
+async function resolveFileHandle(
+  root: FileSystemDirectoryHandle,
+  rel: string,
+): Promise<FileSystemFileHandle | null> {
+  const segments = rel.split('/').filter((s) => s.length > 0);
+  if (segments.length === 0) return null;
+  let dir: FileSystemDirectoryHandle = root;
+  for (let i = 0; i < segments.length - 1; i++) {
+    try {
+      dir = await dir.getDirectoryHandle(segments[i]!);
+    } catch {
+      return null;
+    }
+  }
+  try {
+    return await dir.getFileHandle(segments[segments.length - 1]!);
+  } catch {
+    return null;
+  }
+}
+
+async function walk(
+  dir: FileSystemDirectoryHandle,
+  relDir: string,
+  out: Map<string, FileSystemFileHandle>,
+  onVisit: () => void,
+  skipTestLikeDirs: boolean,
+  ig: Ignore,
+): Promise<void> {
+  for await (const [name, handle] of dir.entries()) {
+    const relPath = relDir ? `${relDir}/${name}` : name;
+    if (handle.kind === 'directory') {
+      if (ALWAYS_SKIP_DIRS.has(name)) continue;
+      if (skipTestLikeDirs && TEST_LIKE_DIRS.has(name)) continue;
+      if (ig.ignores(`${relPath}/`)) continue;
+      await walk(handle as FileSystemDirectoryHandle, relPath, out, onVisit, skipTestLikeDirs, ig);
+      continue;
+    }
+    const ext = extOf(name);
+    if (!SUPPORTED_EXT.has(ext)) continue;
+    if (ig.ignores(relPath)) continue;
+    out.set(relPath, handle as FileSystemFileHandle);
+    onVisit();
+  }
+}
+
+function extOf(name: string): string {
+  const i = name.lastIndexOf('.');
+  return i === -1 ? '' : name.slice(i).toLowerCase();
+}

package/src/analyzer/sources/inMemoryFileSource.ts

@@ -0,0 +1,24 @@
+import type { FileSource } from '../fileSource';
+
+// in-memory FileSource for tests + the worker pipeline
+export function createInMemoryFileSource(
+  rootPath: string,
+  files: Record<string, string>,
+): FileSource {
+  return {
+    rootPath,
+    async list(): Promise<string[]> {
+      return Object.keys(files);
+    },
+    async read(relativePath: string): Promise<string> {
+      const content = files[relativePath];
+      if (content === undefined) {
+        throw new Error(`InMemoryFileSource: file not found "${relativePath}"`);
+      }
+      return content;
+    },
+    async exists(relativePath: string): Promise<boolean> {
+      return relativePath in files;
+    },
+  };
+}

package/src/analyzer/sources/nodeFsFileSource.ts

@@ -0,0 +1,93 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import ignore, { type Ignore } from 'ignore';
+import type { FileSource } from '../fileSource';
+import { ALWAYS_SKIP_DIRS, TEST_LIKE_DIRS } from '../discover';
+
+const SUPPORTED_EXT = new Set(['.ts', '.tsx', '.js', '.jsx', '.vue', '.svelte', '.mjs', '.cjs']);
+
+export interface NodeFsFileSourceOptions {
+  rootPath: string;
+  respectGitignore?: boolean;
+  extraIgnore?: string[];
+  /** Если true (по умолчанию) - не заходим в тест/storybook/cypress/playwright директории. */
+  skipTestLikeDirs?: boolean;
+}
+
+async function loadGitignore(rootPath: string): Promise<Ignore> {
+  const ig = ignore();
+  try {
+    const content = await fs.readFile(path.join(rootPath, '.gitignore'), 'utf8');
+    ig.add(content);
+  } catch {
+    /* no gitignore is fine */
+  }
+  return ig;
+}
+
+export async function createNodeFsFileSource(
+  options: NodeFsFileSourceOptions,
+): Promise<FileSource> {
+  const { rootPath, respectGitignore = true, extraIgnore = [], skipTestLikeDirs = true } = options;
+  const absRoot = path.resolve(rootPath);
+  const ig = respectGitignore ? await loadGitignore(absRoot) : ignore();
+  if (extraIgnore.length > 0) ig.add(extraIgnore);
+
+  return {
+    rootPath: absRoot,
+    async list(): Promise<string[]> {
+      const out: string[] = [];
+      await walk(absRoot, '', ig, out, skipTestLikeDirs);
+      return out.sort();
+    },
+    async read(rel: string): Promise<string> {
+      return fs.readFile(path.join(absRoot, rel), 'utf8');
+    },
+    async exists(rel: string): Promise<boolean> {
+      try {
+        const stat = await fs.stat(path.join(absRoot, rel));
+        return stat.isFile();
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+async function walk(
+  absRoot: string,
+  relDir: string,
+  ig: Ignore,
+  out: string[],
+  skipTestLikeDirs: boolean,
+): Promise<void> {
+  const absDir = path.join(absRoot, relDir);
+  let entries;
+  try {
+    entries = await fs.readdir(absDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const relPath = relDir ? path.posix.join(toPosix(relDir), entry.name) : entry.name;
+
+    if (entry.isDirectory()) {
+      if (ALWAYS_SKIP_DIRS.has(entry.name)) continue;
+      if (skipTestLikeDirs && TEST_LIKE_DIRS.has(entry.name)) continue;
+      if (ig.ignores(`${relPath}/`)) continue;
+      await walk(absRoot, relPath, ig, out, skipTestLikeDirs);
+      continue;
+    }
+
+    if (!entry.isFile()) continue;
+    if (ig.ignores(relPath)) continue;
+    const ext = path.extname(entry.name).toLowerCase();
+    if (!SUPPORTED_EXT.has(ext)) continue;
+    out.push(relPath);
+  }
+}
+
+function toPosix(p: string): string {
+  return p.split(path.sep).join('/');
+}

package/src/analyzer/sources/tauriFileSource.ts

@@ -0,0 +1,68 @@
+import type { FileSource } from '../fileSource';
+
+interface TauriInvoke {
+  <T>(cmd: string, args?: Record<string, unknown>): Promise<T>;
+}
+
+export interface TauriFileSourceOptions {
+  rootPath: string;
+  rootName?: string;
+  invoke: TauriInvoke;
+  /** Дополнительные ignore-globs (gitignore-синтаксис), напр. ['*.test.ts']. */
+  extraIgnoreGlobs?: string[];
+  /** Жёсткий лимит размера читаемого файла, байт. По умолчанию 2 МБ. */
+  maxFileBytes?: number;
+}
+
+export async function createTauriFileSource(options: TauriFileSourceOptions): Promise<FileSource> {
+  const { rootPath, rootName, invoke, extraIgnoreGlobs, maxFileBytes } = options;
+  let listing: Promise<Set<string>> | null = null;
+
+  async function ensureListed(): Promise<Set<string>> {
+    if (!listing) {
+      listing = invoke<string[]>('read_project_tree', {
+        root: rootPath,
+        options: {
+          extraIgnoreGlobs: extraIgnoreGlobs ?? [],
+          followSymlinks: false,
+        },
+      }).then((paths) => new Set(paths));
+    }
+    return listing;
+  }
+
+  return {
+    rootPath: rootName ?? rootPath,
+    async list(): Promise<string[]> {
+      const set = await ensureListed();
+      return [...set].sort();
+    },
+    async read(relativePath: string): Promise<string> {
+      return invoke<string>('read_file', {
+        root: rootPath,
+        relative: relativePath,
+        options: maxFileBytes !== undefined ? { maxBytes: maxFileBytes } : {},
+      });
+    },
+    async readMany(relativePaths: readonly string[]): Promise<Record<string, string>> {
+      return invoke<Record<string, string>>('read_files', {
+        root: rootPath,
+        relatives: relativePaths,
+        options: maxFileBytes !== undefined ? { maxBytes: maxFileBytes } : {},
+      });
+    },
+    async exists(relativePath: string): Promise<boolean> {
+      // listing is extension-filtered; configs miss the cache and need file_exists
+      const set = await ensureListed();
+      if (set.has(relativePath)) return true;
+      try {
+        return await invoke<boolean>('file_exists', {
+          root: rootPath,
+          relative: relativePath,
+        });
+      } catch {
+        return false;
+      }
+    },
+  };
+}

package/src/analyzer/suggestContracts.ts

@@ -0,0 +1,214 @@
+// Auto-suggest contract rules.
+//
+// Walks an already-built scan and proposes a `.archora.json -> contracts`
+// block that codifies the architectural intent visible in the code:
+//
+//   - `features-isolation` boundary when there's a `features/*` folder,
+//     cross-instance `must-not` between siblings.
+//   - `layer-discipline` boundaries derived from observed layer violations:
+//     for every (lowerLayer -> higherLayer) pair that the code already
+//     respects (no violations going the wrong way), we don't propose;
+//     for pairs the user violates, we DO propose `must-not` so they get
+//     a CI gate the moment they fix the existing violations.
+//   - `no-cycles` budgets for folders that currently have 0 cycles - locks
+//     them in.
+//
+// The generator never proposes rules that already exist in the loaded
+// `.archora.json` (matched by `name` + same `from`/`to`/`module` shape).
+// CLI consumes the output via `archora suggest contracts`; UI offers
+// "copy as .archora.json".
+
+import type { ContractsConfig } from '../config/frontScopeConfig';
+import { detectLayer, LAYER_ORDER, type Layer } from './layers';
+import type { Cycle, DependencyEdge, ModuleNode } from './types';
+
+export interface SuggestContractsInput {
+  modules: ModuleNode[];
+  edges: DependencyEdge[];
+  cycles: Cycle[];
+  /** Current contracts block, if any - used to suppress duplicates. */
+  existing?: ContractsConfig;
+}
+
+/**
+ * Structured reason for i18n consumers (UI). The `key` is a stable i18n key
+ * the host can translate; `params` are interpolation values. CLI/JSON readers
+ * keep using the plain `reasons` map.
+ */
+export interface SuggestedReason {
+  key: string;
+  params: Record<string, string | number>;
+}
+
+export interface SuggestedContracts {
+  contracts: ContractsConfig;
+  /** Human-readable explanations per rule, keyed by `rule.name`. English. */
+  reasons: Record<string, string>;
+  /** i18n-friendly explanations per rule, same keys as `reasons`. */
+  reasonKeys: Record<string, SuggestedReason>;
+}
+
+const FEATURES_GLOB = 'src/features/*/**';
+const FEATURE_RULE_NAME = 'features-isolation';
+
+export function suggestContracts(input: SuggestContractsInput): SuggestedContracts {
+  const reasons: Record<string, string> = {};
+  const reasonKeys: Record<string, SuggestedReason> = {};
+  const out: ContractsConfig = {};
+  const existing = input.existing ?? {};
+
+  const boundaries = collectBoundarySuggestions(input, existing, reasons, reasonKeys);
+  if (boundaries.length > 0) out.boundaries = boundaries;
+
+  const budgets = collectBudgetSuggestions(input, existing, reasons, reasonKeys);
+  if (budgets.length > 0) out.budgets = budgets;
+
+  return { contracts: out, reasons, reasonKeys };
+}
+
+function collectBoundarySuggestions(
+  input: SuggestContractsInput,
+  existing: ContractsConfig,
+  reasons: Record<string, string>,
+  reasonKeys: Record<string, SuggestedReason>,
+): NonNullable<ContractsConfig['boundaries']> {
+  const out: NonNullable<ContractsConfig['boundaries']> = [];
+  const existingByName = new Set(existing.boundaries?.map((r) => r.name) ?? []);
+
+  // 1) features-isolation
+  const hasFeatures = input.modules.some((m) => m.id.startsWith('src/features/'));
+  if (hasFeatures && !existingByName.has(FEATURE_RULE_NAME)) {
+    // Only propose if at least one cross-feature edge currently exists or
+    // is plausible (multiple feature folders). One-feature projects get a
+    // less useful rule.
+    const featureRoots = collectImmediateChildrenUnder(input.modules, 'src/features/');
+    if (featureRoots.size >= 2) {
+      out.push({
+        name: FEATURE_RULE_NAME,
+        from: FEATURES_GLOB,
+        to: FEATURES_GLOB,
+        mode: 'must-not',
+        crossInstance: true,
+        description: 'Features must be self-contained. Cross-feature imports go through shared/.',
+      });
+      reasons[FEATURE_RULE_NAME] =
+        `Found ${featureRoots.size} feature folders under src/features/. The rule forbids sibling-to-sibling imports.`;
+      reasonKeys[FEATURE_RULE_NAME] = {
+        key: 'featuresIsolation',
+        params: { count: featureRoots.size },
+      };
+    }
+  }
+
+  // 2) layer-discipline: propose `must-not` for every observed violation
+  //    direction we can name from FSD layers. We collapse all per-edge
+  //    layer violations into per-(fromLayer,toLayer) suggestions.
+  const layerPairs = new Map<string, { fromLayer: Layer; toLayer: Layer; count: number }>();
+  for (const e of input.edges) {
+    if (e.kind === 'type-only') continue;
+    const fromLayer = detectLayer(e.from);
+    const toLayer = detectLayer(e.to);
+    if (fromLayer === 'unknown' || toLayer === 'unknown') continue;
+    const fromRank = LAYER_ORDER.indexOf(fromLayer);
+    const toRank = LAYER_ORDER.indexOf(toLayer);
+    // LAYER_ORDER goes UI -> core (smaller rank = closer to UI).
+    // Allowed direction: smaller rank importing larger rank (UI pulls in
+    // shared/core). Violation: bigger rank importing smaller rank
+    // (core/shared reaching up into widgets/features).
+    if (fromRank <= toRank) continue;
+    const key = `${fromLayer}->${toLayer}`;
+    const cur = layerPairs.get(key);
+    if (cur) cur.count += 1;
+    else layerPairs.set(key, { fromLayer, toLayer, count: 1 });
+  }
+  for (const { fromLayer, toLayer, count } of layerPairs.values()) {
+    const name = `layer-${fromLayer}-not-${toLayer}`;
+    if (existingByName.has(name)) continue;
+    out.push({
+      name,
+      from: `src/${fromLayer}/**`,
+      to: `src/${toLayer}/**`,
+      mode: 'must-not',
+      severity: 'error',
+      description: `${fromLayer} should not import from ${toLayer} (FSD layer order).`,
+    });
+    reasons[name] =
+      `Observed ${count} edge(s) from ${fromLayer} into ${toLayer}; codify the rule to prevent regression after the fix.`;
+    reasonKeys[name] = {
+      key: 'layerDiscipline',
+      params: { count, fromLayer, toLayer },
+    };
+  }
+
+  return out;
+}
+
+function collectBudgetSuggestions(
+  input: SuggestContractsInput,
+  existing: ContractsConfig,
+  reasons: Record<string, string>,
+  reasonKeys: Record<string, SuggestedReason>,
+): NonNullable<ContractsConfig['budgets']> {
+  const out: NonNullable<ContractsConfig['budgets']> = [];
+  const existingByName = new Set(existing.budgets?.map((r) => r.name) ?? []);
+
+  // shared/** + entities/** + core/** are common "no-cycles" candidates.
+  // Only propose when the current scan has zero cycles touching them - a
+  // suggestion that fails on day one is worse than no suggestion.
+  const candidates: { glob: string; label: string }[] = [
+    { glob: 'src/shared/**', label: 'shared' },
+    { glob: 'src/entities/**', label: 'entities' },
+    { glob: 'src/core/**', label: 'core' },
+    { glob: 'src/shared/ui/**', label: 'shared/ui' },
+  ];
+  for (const c of candidates) {
+    const name = `no-cycles-${c.label.replace(/\//gu, '-')}`;
+    if (existingByName.has(name)) continue;
+    if (!hasModulesUnder(input.modules, c.glob)) continue;
+    if (countCyclesUnder(input.cycles, c.glob) > 0) continue;
+    out.push({
+      name,
+      module: c.glob,
+      maxCycles: 0,
+      severity: 'warning',
+      description: `Lock cycle count at 0 in ${c.label}; the layer is currently clean.`,
+    });
+    reasons[name] = `${c.label} currently has 0 cycles - lock it in to catch regressions.`;
+    reasonKeys[name] = { key: 'noCycles', params: { label: c.label } };
+  }
+
+  return out;
+}
+
+function collectImmediateChildrenUnder(modules: ModuleNode[], prefix: string): Set<string> {
+  const out = new Set<string>();
+  for (const m of modules) {
+    if (!m.id.startsWith(prefix)) continue;
+    const tail = m.id.slice(prefix.length);
+    const slash = tail.indexOf('/');
+    if (slash <= 0) continue;
+    out.add(tail.slice(0, slash));
+  }
+  return out;
+}
+
+// Glob support is intentionally narrow: we only emit globs that follow the
+// `prefix/**` shape, so a string-prefix check is exact.
+function globPrefix(glob: string): string {
+  const idx = glob.indexOf('/**');
+  return idx === -1 ? glob : glob.slice(0, idx + 1);
+}
+
+function hasModulesUnder(modules: ModuleNode[], glob: string): boolean {
+  const p = globPrefix(glob);
+  return modules.some((m) => m.id.startsWith(p));
+}
+
+function countCyclesUnder(cycles: Cycle[], glob: string): number {
+  const p = globPrefix(glob);
+  let n = 0;
+  for (const c of cycles) {
+    if (c.modules.some((id) => id.startsWith(p))) n += 1;
+  }
+  return n;
+}