@monoes/monograph 1.1.0 → 1.2.0

package/src/analysis/workspace-filter.ts

@@ -0,0 +1,97 @@
+export interface SubsetFilter {
+  roots: string[];
+  test(filePath: string): boolean;
+}
+
+export function createSubsetFilter(roots: string[]): SubsetFilter {
+  // Normalize roots to ensure they end with '/'
+  const normalizedRoots = roots.map((root) => (root.endsWith('/') ? root : root + '/'));
+
+  return {
+    roots: normalizedRoots,
+    test(filePath: string): boolean {
+      return normalizedRoots.some((root) => filePath.startsWith(root));
+    },
+  };
+}
+
+export function filterToWorkspaces<T extends { filePath?: string | null }>(
+  items: T[],
+  workspaceRoots: string[],
+): T[] {
+  const filter = createSubsetFilter(workspaceRoots);
+  return items.filter((item) => item.filePath != null && filter.test(item.filePath));
+}
+
+export function filterGroupsByWorkspace<T extends { instances: Array<{ filePath: string }> }>(
+  groups: T[],
+  workspaceRoots: string[],
+): T[] {
+  const filter = createSubsetFilter(workspaceRoots);
+  return groups.filter((group) => group.instances.some((instance) => filter.test(instance.filePath)));
+}
+
+// ── Round 8: gitignore-style negation patterns + changed-file scoping ──────
+
+export interface WorkspaceFilterPattern {
+  pattern: string;
+  negated: boolean;   // true if pattern starts with '!'
+  isGlob: boolean;
+}
+
+/** Parse a workspace filter string into a structured pattern. */
+export function parseWorkspaceFilterPattern(raw: string): WorkspaceFilterPattern {
+  const negated = raw.startsWith('!');
+  const pattern = negated ? raw.slice(1) : raw;
+  const isGlob = pattern.includes('*') || pattern.includes('?');
+  return { pattern, negated, isGlob };
+}
+
+/** Match a workspace name against a gitignore-style pattern (supports ! negation and globs). */
+export function matchWorkspacePattern(name: string, pattern: WorkspaceFilterPattern): boolean {
+  if (pattern.isGlob) {
+    const re = new RegExp('^' + pattern.pattern.replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
+    return re.test(name);
+  }
+  return name === pattern.pattern;
+}
+
+/** Resolve a list of workspace names against a list of filter patterns with negation. */
+export function resolveWorkspaceFilters(
+  names: string[],
+  patterns: string[],
+): string[] {
+  if (patterns.length === 0) return names;
+  const parsed = patterns.map(parseWorkspaceFilterPattern);
+  return names.filter(name => {
+    let included = false;
+    for (const p of parsed) {
+      if (matchWorkspacePattern(name, p)) {
+        included = !p.negated;
+      }
+    }
+    return included;
+  });
+}
+
+/** Format available workspace names for display, capping at 10 with overflow count. */
+export function formatAvailableWorkspaces(names: string[]): string {
+  const MAX = 10;
+  if (names.length <= MAX) return names.join(', ');
+  return `${names.slice(0, MAX).join(', ')} ... and ${names.length - MAX} more (${names.length} total)`;
+}
+
+/** Map a set of changed file paths to workspace indices that contain at least one changed file. */
+export function workspacesContainingAny(
+  changedFiles: string[],
+  workspaceRoots: string[],
+): number[] {
+  const indices: number[] = [];
+  for (let i = 0; i < workspaceRoots.length; i++) {
+    const root = workspaceRoots[i].replace(/\\/g, '/').replace(/\/$/, '');
+    if (changedFiles.some(f => f.replace(/\\/g, '/').startsWith(root + '/'))) {
+      indices.push(i);
+    }
+  }
+  return indices;
+}

package/src/analyze/boundary-analysis.ts

@@ -0,0 +1,129 @@
+import type { ResolvedBoundaryConfig } from '../config/boundary-config.js';
+import { classifyZone, isImportAllowed } from '../config/boundary-config.js';
+import type { ModuleNode } from '../graph/node-types.js';
+import { ModuleNodeFlags } from '../graph/node-types.js';
+import type { FallowBoundaryViolation } from '../results/fallow-results.js';
+
+export interface BoundaryAnalysisResult {
+  violations: FallowBoundaryViolation[];
+  checkedEdges: number;
+  uncheckedFiles: number;
+}
+
+function isReachableOrEntry(mod: ModuleNode): boolean {
+  return (
+    (mod.flags & ModuleNodeFlags.REACHABLE) !== 0 ||
+    (mod.flags & ModuleNodeFlags.ENTRY_POINT) !== 0
+  );
+}
+
+function hasRules(config: ResolvedBoundaryConfig, zoneName: string): boolean {
+  return config.rules.some(r => r.from.name === zoneName);
+}
+
+export function findBoundaryViolations(
+  modules: ModuleNode[],
+  config: ResolvedBoundaryConfig,
+): FallowBoundaryViolation[] {
+  if (config.zones.length === 0) return [];
+
+  const zoneCache = new Map<string, string | undefined>();
+
+  const classify = (filePath: string): string | undefined => {
+    if (zoneCache.has(filePath)) return zoneCache.get(filePath);
+    const zone = classifyZone(config, filePath);
+    zoneCache.set(filePath, zone);
+    return zone;
+  };
+
+  const filePathByPath = new Map<string, ModuleNode>(modules.map(m => [m.filePath, m]));
+
+  const violations: FallowBoundaryViolation[] = [];
+
+  for (const mod of modules) {
+    if (!isReachableOrEntry(mod)) continue;
+
+    const fromZone = classify(mod.filePath);
+    if (!fromZone) continue;
+
+    if (!hasRules(config, fromZone)) continue;
+
+    for (const edge of mod.reExports) {
+      const toPath = edge.toFile;
+      const toZone = classify(toPath);
+      if (!toZone) continue;
+      if (fromZone === toZone) continue;
+
+      if (!isImportAllowed(config, mod.filePath, toPath)) {
+        violations.push({
+          fromPath: mod.filePath,
+          toPath,
+          fromZone,
+          toZone,
+          importSpecifier: toPath,
+          line: 1,
+          col: 0,
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
+export function analyzeBoundaries(
+  modules: ModuleNode[],
+  config: ResolvedBoundaryConfig,
+): BoundaryAnalysisResult {
+  if (config.zones.length === 0) {
+    return { violations: [], checkedEdges: 0, uncheckedFiles: 0 };
+  }
+
+  const zoneCache = new Map<string, string | undefined>();
+
+  const classify = (filePath: string): string | undefined => {
+    if (zoneCache.has(filePath)) return zoneCache.get(filePath);
+    const zone = classifyZone(config, filePath);
+    zoneCache.set(filePath, zone);
+    return zone;
+  };
+
+  const violations: FallowBoundaryViolation[] = [];
+  let checkedEdges = 0;
+  let uncheckedFiles = 0;
+
+  for (const mod of modules) {
+    if (!isReachableOrEntry(mod)) continue;
+
+    const fromZone = classify(mod.filePath);
+    if (!fromZone) {
+      uncheckedFiles++;
+      continue;
+    }
+
+    if (!hasRules(config, fromZone)) continue;
+
+    for (const edge of mod.reExports) {
+      const toPath = edge.toFile;
+      checkedEdges++;
+
+      const toZone = classify(toPath);
+      if (!toZone) continue;
+      if (fromZone === toZone) continue;
+
+      if (!isImportAllowed(config, mod.filePath, toPath)) {
+        violations.push({
+          fromPath: mod.filePath,
+          toPath,
+          fromZone,
+          toZone,
+          importSpecifier: toPath,
+          line: 1,
+          col: 0,
+        });
+      }
+    }
+  }
+
+  return { violations, checkedEdges, uncheckedFiles };
+}

package/src/analyze/predicates/file.ts

@@ -0,0 +1,86 @@
+import path from "node:path";
+
+export function isDeclarationFile(filePath: string): boolean {
+  const name = path.basename(filePath);
+  return name.endsWith(".d.ts") || name.endsWith(".d.mts") || name.endsWith(".d.cts");
+}
+
+export function isHtmlFile(filePath: string): boolean {
+  return path.extname(filePath) === ".html";
+}
+
+export function isConfigFile(filePath: string): boolean {
+  const name = path.basename(filePath);
+
+  if (name.startsWith(".") && !name.startsWith("..")) {
+    const lower = name.toLowerCase();
+    if (lower.includes("rc.")) {
+      return true;
+    }
+  }
+
+  const configPatterns = [
+    "babel.config.",
+    "rollup.config.",
+    "webpack.config.",
+    "postcss.config.",
+    "stencil.config.",
+    "metro.config.",
+    "tsup.config.",
+    "unbuild.config.",
+    "esbuild.config.",
+    "swc.config.",
+    "turbo.",
+    "jest.config.",
+    "jest.setup.",
+    "vitest.config.",
+    "vitest.ci.config.",
+    "vitest.setup.",
+    "vitest.workspace.",
+    "playwright.config.",
+    "cypress.config.",
+    "karma.conf.",
+    "eslint.config.",
+    "prettier.config.",
+    "stylelint.config.",
+    "lint-staged.config.",
+    "commitlint.config.",
+    "next.config.",
+    "next-sitemap.config.",
+    "nuxt.config.",
+    "astro.config.",
+    "sanity.config.",
+    "vite.config.",
+    "tailwind.config.",
+    "drizzle.config.",
+    "knexfile.",
+    "sentry.client.config.",
+    "sentry.server.config.",
+    "sentry.edge.config.",
+    "react-router.config.",
+    "typedoc.",
+    "knip.config.",
+    "fallow.config.",
+    "i18next-parser.config.",
+    "codegen.config.",
+    "graphql.config.",
+    "npmpackagejsonlint.config.",
+    "release-it.",
+    "release.config.",
+    "contentlayer.config.",
+    "next-env.d.",
+    "env.d.",
+    "vite-env.d.",
+  ];
+
+  return configPatterns.some((p) => name.startsWith(p));
+}
+
+export function isTestFile(filePath: string): boolean {
+  return (
+    filePath.includes("/__tests__/") ||
+    filePath.includes("/.test.") ||
+    filePath.includes(".test.") ||
+    filePath.includes(".spec.")
+  );
+}

package/src/analyze/predicates/import.ts

@@ -0,0 +1,90 @@
+export const BUILTIN_MODULES: Set<string> = new Set([
+  "assert",
+  "assert/strict",
+  "async_hooks",
+  "buffer",
+  "child_process",
+  "cluster",
+  "console",
+  "constants",
+  "crypto",
+  "dgram",
+  "diagnostics_channel",
+  "dns",
+  "dns/promises",
+  "domain",
+  "events",
+  "fs",
+  "fs/promises",
+  "http",
+  "http2",
+  "https",
+  "inspector",
+  "inspector/promises",
+  "module",
+  "net",
+  "os",
+  "path",
+  "path/posix",
+  "path/win32",
+  "perf_hooks",
+  "process",
+  "punycode",
+  "querystring",
+  "readline",
+  "readline/promises",
+  "repl",
+  "stream",
+  "stream/consumers",
+  "stream/promises",
+  "stream/web",
+  "string_decoder",
+  "sys",
+  "test",
+  "test/reporters",
+  "timers",
+  "timers/promises",
+  "tls",
+  "trace_events",
+  "tty",
+  "url",
+  "util",
+  "util/types",
+  "v8",
+  "vm",
+  "wasi",
+  "worker_threads",
+  "zlib",
+]);
+
+export function isVirtualModule(specifier: string): boolean {
+  return specifier.startsWith("virtual:");
+}
+
+export function isBuiltinModule(specifier: string): boolean {
+  if (specifier.startsWith("bun:")) return true;
+  if (specifier.startsWith("cloudflare:")) return true;
+  if (specifier.startsWith("sass:")) return true;
+  if (specifier === "std" || specifier.startsWith("std/")) return true;
+
+  const stripped = specifier.startsWith("node:") ? specifier.slice(5) : specifier;
+  return BUILTIN_MODULES.has(stripped);
+}
+
+export function isImplicitDependency(specifier: string): boolean {
+  if (specifier.startsWith("@types/")) return true;
+
+  const implicitDeps = new Set([
+    "react-dom",
+    "react-dom/client",
+    "react-native",
+    "@next/font",
+    "@next/mdx",
+    "@next/bundle-analyzer",
+    "@next/env",
+    "utf-8-validate",
+    "bufferutil",
+  ]);
+
+  return implicitDeps.has(specifier);
+}

package/src/analyze/predicates/lifecycle.ts

@@ -0,0 +1,55 @@
+export const ANGULAR_LIFECYCLE_METHODS: Set<string> = new Set([
+  "ngOnInit",
+  "ngOnDestroy",
+  "ngOnChanges",
+  "ngDoCheck",
+  "ngAfterContentInit",
+  "ngAfterContentChecked",
+  "ngAfterViewInit",
+  "ngAfterViewChecked",
+  "ngAcceptInputType",
+  "canActivate",
+  "canDeactivate",
+  "canActivateChild",
+  "canMatch",
+  "resolve",
+  "intercept",
+  "transform",
+  "validate",
+  "registerOnChange",
+  "registerOnTouched",
+  "writeValue",
+  "setDisabledState",
+]);
+
+export const REACT_LIFECYCLE_METHODS: Set<string> = new Set([
+  "render",
+  "componentDidMount",
+  "componentDidUpdate",
+  "componentWillUnmount",
+  "shouldComponentUpdate",
+  "getSnapshotBeforeUpdate",
+  "getDerivedStateFromProps",
+  "getDerivedStateFromError",
+  "componentDidCatch",
+  "componentWillMount",
+  "componentWillReceiveProps",
+  "componentWillUpdate",
+  "UNSAFE_componentWillMount",
+  "UNSAFE_componentWillReceiveProps",
+  "UNSAFE_componentWillUpdate",
+  "getChildContext",
+  "contextType",
+]);
+
+export function isAngularLifecycleMethod(name: string): boolean {
+  return ANGULAR_LIFECYCLE_METHODS.has(name);
+}
+
+export function isReactLifecycleMethod(name: string): boolean {
+  return REACT_LIFECYCLE_METHODS.has(name);
+}
+
+export function isFrameworkLifecycleMethod(name: string): boolean {
+  return isAngularLifecycleMethod(name) || isReactLifecycleMethod(name);
+}

package/src/analyze/unused-deps.ts

@@ -0,0 +1,70 @@
+export type DepCategory =
+  | "dependencies"
+  | "devDependencies"
+  | "optionalDependencies"
+  | "peerDependencies";
+
+export interface UnusedDepResult {
+  name: string;
+  category: DepCategory;
+  reason: string;
+}
+
+export interface UnresolvedImportResult {
+  specifier: string;
+  filePath: string;
+}
+
+export interface DepCategoryConfig {
+  skipDev?: boolean;
+  skipOptional?: boolean;
+  skipPeer?: boolean;
+}
+
+export function findUnusedDependencies(
+  usedPackages: Set<string>,
+  declaredDeps: Record<DepCategory, string[]>,
+  config: DepCategoryConfig = {}
+): UnusedDepResult[] {
+  const results: UnusedDepResult[] = [];
+
+  const categories: Array<{ key: DepCategory; skip?: boolean }> = [
+    { key: "dependencies" },
+    { key: "devDependencies", skip: config.skipDev },
+    { key: "optionalDependencies", skip: config.skipOptional },
+    { key: "peerDependencies", skip: config.skipPeer },
+  ];
+
+  for (const { key, skip } of categories) {
+    if (skip) continue;
+    const deps = declaredDeps[key] ?? [];
+    for (const dep of deps) {
+      if (!usedPackages.has(dep)) {
+        results.push({
+          name: dep,
+          category: key,
+          reason: `declared in ${key} but never imported`,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+export function findUnresolvedImports(
+  importSpecifiers: Array<{ specifier: string; filePath: string }>,
+  resolvedPackages: Set<string>
+): UnresolvedImportResult[] {
+  return importSpecifiers.filter(({ specifier }) => !resolvedPackages.has(specifier));
+}
+
+export function findTypeOnlyDependencies(
+  usedInProduction: Set<string>,
+  usedInTypes: Set<string>,
+  deps: string[]
+): string[] {
+  return deps.filter(
+    (dep) => !usedInProduction.has(dep) && usedInTypes.has(dep)
+  );
+}

package/src/analyze/unused-exports.ts

@@ -0,0 +1,145 @@
+import type { ModuleNode, ExportSymbol } from '../graph/node-types.js';
+import { isEntryPoint, ModuleNodeFlags } from '../graph/node-types.js';
+import type { FallowUnusedExport, FallowDuplicateExport, FallowDuplicateLocation } from '../results/fallow-results.js';
+
+export interface UnusedExportsOptions {
+  isEntryPoint?: (path: string) => boolean;
+  ignorePaths?: string[];
+  includeTypeOnlyExports?: boolean;
+  maxDuplicates?: number;
+}
+
+function matchesIgnorePath(filePath: string, patterns: string[]): boolean {
+  for (const pattern of patterns) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    if (new RegExp(escaped).test(filePath)) return true;
+  }
+  return false;
+}
+
+function buildReferencedNamesMap(modules: ModuleNode[]): Map<string, Set<string>> {
+  const referencedByFile = new Map<string, Set<string>>();
+
+  for (const mod of modules) {
+    for (const ref of mod.references) {
+      const target = ref.fromFile;
+      if (!referencedByFile.has(target)) {
+        referencedByFile.set(target, new Set());
+      }
+      referencedByFile.get(target)!.add(ref.name);
+    }
+  }
+
+  return referencedByFile;
+}
+
+function buildReExportedNamesMap(modules: ModuleNode[]): Map<string, Set<string>> {
+  const reExportedByFile = new Map<string, Set<string>>();
+
+  for (const mod of modules) {
+    for (const edge of mod.reExports) {
+      if (!reExportedByFile.has(edge.fromFile)) {
+        reExportedByFile.set(edge.fromFile, new Set());
+      }
+      if (edge.symbol) {
+        reExportedByFile.get(edge.fromFile)!.add(edge.symbol);
+      }
+    }
+  }
+
+  return reExportedByFile;
+}
+
+function isModuleEntryPoint(mod: ModuleNode, opts: UnusedExportsOptions): boolean {
+  if (opts.isEntryPoint && opts.isEntryPoint(mod.filePath)) return true;
+  return isEntryPoint(mod);
+}
+
+function hasCjsExports(mod: ModuleNode): boolean {
+  return (mod.flags & ModuleNodeFlags.CJS_EXPORTS) !== 0;
+}
+
+export function findUnusedExports(
+  modules: ModuleNode[],
+  opts: UnusedExportsOptions = {},
+): FallowUnusedExport[] {
+  const {
+    ignorePaths = [],
+    includeTypeOnlyExports = true,
+  } = opts;
+
+  const referencedByFile = buildReferencedNamesMap(modules);
+  const reExportedNames = buildReExportedNamesMap(modules);
+
+  const reachableFileIds = new Set(
+    modules
+      .filter(m => (m.flags & ModuleNodeFlags.REACHABLE) !== 0)
+      .map(m => m.filePath),
+  );
+
+  const results: FallowUnusedExport[] = [];
+
+  for (const mod of modules) {
+    if (isModuleEntryPoint(mod, opts)) continue;
+    if (ignorePaths.length > 0 && matchesIgnorePath(mod.filePath, ignorePaths)) continue;
+    if (hasCjsExports(mod) && mod.exports.length === 0) continue;
+
+    const reachable = reachableFileIds.has(mod.filePath);
+    const referenced = referencedByFile.get(mod.filePath) ?? new Set<string>();
+    const reExportedHere = reExportedNames.get(mod.filePath) ?? new Set<string>();
+
+    for (const exp of mod.exports) {
+      if (!includeTypeOnlyExports && exp.isType) continue;
+
+      const isReferenced = referenced.has(exp.name);
+      if (isReferenced) continue;
+
+      const isReExport = exp.isReExport || reExportedHere.has(exp.name);
+
+      if (!reachable && !isReExport) continue;
+
+      const line = exp.line ?? 1;
+
+      results.push({
+        filePath: mod.filePath,
+        line,
+        col: 0,
+        exportName: exp.name,
+        spanStart: 0,
+        isReExport,
+        isTypeOnly: exp.isType,
+      });
+    }
+  }
+
+  return results;
+}
+
+export function findDuplicateExports(
+  modules: ModuleNode[],
+): Array<{ name: string; files: Array<{ filePath: string; line: number; col: number }> }> {
+  const byName = new Map<string, Array<{ filePath: string; line: number; col: number }>>();
+
+  for (const mod of modules) {
+    for (const exp of mod.exports) {
+      if (!byName.has(exp.name)) {
+        byName.set(exp.name, []);
+      }
+      byName.get(exp.name)!.push({
+        filePath: mod.filePath,
+        line: exp.line ?? 1,
+        col: 0,
+      });
+    }
+  }
+
+  const results: Array<{ name: string; files: Array<{ filePath: string; line: number; col: number }> }> = [];
+
+  for (const [name, files] of byName) {
+    if (files.length > 1) {
+      results.push({ name, files });
+    }
+  }
+
+  return results;
+}