@angular-modernizer/plugin-architecture

Architecture and code quality analysis plugin for the Angular Modernization Platform.

Overview

The plugin provides 17 analysis rules for structural problems in Angular code bases: import cycles, imports across layer boundaries, files in the wrong layer, oversized classes and components, services that mix concerns, and groups of shared code that could become a library. All rules only report; the plugin has no transformation or validation rules. Fixes are done by transform rules in other plugins (for example the service bag split in @angular-modernizer/plugin-angular).

ArchitecturePlugin is the entry point for the kernel. Besides the rules, the package exports building blocks that other plugins and tools reuse: the value-import graph, the module resolver, the layer path matcher, the library extraction scanner and helpers for responsibility patterns and RxJS subscription safety.

Installation

npm install @angular-modernizer/plugin-architecture
Copy

The package is an ES module and needs Node.js ^20.19.0 || ^22.12.0 || >=24.0.0. It depends on @angular-modernizer/plugin-system, @angular-modernizer/api, @angular-modernizer/core and ts-morph.

Analysis Rules

The first ten rule classes are exported (CircularDependencyRule, ImportDirectionViolationRule, LayerBoundaryViolationRule, ContentPlacementRule, GodObjectRule, ComponentComplexityRule, ServiceArchitectureRule, ServiceBagAnalysisRule, StaticInStatefulClassRule, LibraryExtractionAnalysisRule). The last seven are only available through ArchitecturePlugin.getAnalysisRules().

Three rule IDs use the solid: prefix; the rules belong to this plugin.

Configuration

ArchitecturePlugin.initialize() reads .angular-modernizer.json from the project root of the kernel (the directory of tsConfigPath, otherwise the current working directory). If the file cannot be loaded, the error is logged and all rules run with their defaults and without layers.

Layers

architecture:layer-boundary-violation and architecture:content-placement need a layer topology. Without it both rules report nothing.

{
  "layers": [
    {
      "name": "core",
      "alias": "@core",
      "paths": ["src/app/core/**"],
      "canImportFrom": []
    },
    {
      "name": "shared",
      "alias": "@shared",
      "paths": ["src/app/shared/**"],
      "canImportFrom": ["@core"]
    },
    {
      "name": "features",
      "alias": "@features",
      "paths": ["src/app/features/**"],
      "canImportFrom": ["@core", "@shared"]
    }
  ]
}
Copy

• name: layer name used in messages and in canImportFrom
• alias: tsconfig path alias of the layer
• paths: globs relative to the project root. A layer without paths uses the directory its alias maps to in tsconfig paths. The most specific matching pattern wins, independent of the order of the layers.
• canImportFrom: names or aliases of the layers this layer may import from. An empty array forbids imports from all other layers.
• level (optional): position in the hierarchy, lower = more foundational. When both layers of an import have a level, imports into the same or a lower level are allowed and canImportFrom only lists the allowed imports into higher levels.

The layer-boundary rule checks every import and export ... from. Specifiers are resolved with TypeScript module resolution (tsconfig paths, baseUrl, relative paths, index.ts); unresolved aliased imports fall back to alias-prefix matching. Type-only imports are reported too and marked with typeOnly: true in the metadata.

Imports can be exempted with a project comment marker, none is built in: with "rules": { "architecture:layer-boundary-violation": { "suppressionComments": ["arch-ignore"] } } an import is skipped when a comment on its line or on the line directly above starts with arch-ignore.

Layers from an external source

A project that already defines its layers for an arch-validator script can reference that module instead of repeating it:

{
  "layersSource": {
    "format": "arch-validator",
    "path": "tools/arch-validator/config.js",
    "exportName": "CONFIG"
  }
}
Copy

Each layer key becomes name, paths becomes [key + '/**'], pathAlias becomes alias, allowedImports becomes canImportFrom and level is kept, so the validator's level semantics apply. The validator's own suppression comment is not taken over; set it with suppressionComments. When both layers and layersSource are set, layersSource wins and the differences are logged and returned by ArchitecturePlugin.getLayerDriftWarnings().

Content placement

architecture:content-placement also needs a placement map: the layers (names or aliases) allowed per content type. Content types: service, component, guard, interceptor, directive, pipe, model, utility.

{
  "rules": {
    "architecture:content-placement": {
      "placement": {
        "service": ["@core", "@shared"],
        "guard": ["@core"],
        "component": ["@shared", "@features"]
      }
    }
  }
}
Copy

Barrel files (index.ts, public-api.ts, exports.ts), specs, tests, config files and declaration files are skipped.

Library extraction

architecture:library-extraction-opportunity reads these fields from rules['architecture:library-extraction-opportunity']:

The other fields of the config type (libraryType, outputFolder, libraryPrefix, ...) are used by the library extraction transform, not by this rule.

The scan covers the whole project. The rule runs it once per project and file count and reports each opportunity once, at its primary file.

Other rules

The remaining rules have fixed thresholds and need no configuration. solid:circular-dependency resolves imports with the tsconfig the project was loaded from (else the nearest tsconfig.json) and reads files from disk, so the result does not depend on which files a scan has loaded.

Usage

Via MCP

The scan-architecture MCP tool runs this plugin; scan-all runs it together with the other analysis plugins.

{
  "rootPath": "/path/to/angular/project",
  "rules": ["solid:circular-dependency", "architecture:layer-boundary-violation"]
}
Copy

Without rules, all 17 rules run.

With the Kernel

import path from 'node:path';
import { Kernel } from '@angular-modernizer/core';
import { createPublicApi } from '@angular-modernizer/api';
import { ContextFactory } from '@angular-modernizer/plugin-system';
import { ArchitecturePlugin } from '@angular-modernizer/plugin-architecture';

const kernel = new Kernel({
  tsConfigPath: path.join(projectPath, 'tsconfig.json'),
  plugins: [new ArchitecturePlugin()],
});
await kernel.initialize();

const project = kernel.getProject();
const api = createPublicApi(project);
const rules = kernel
  .getPlugin('@angular-modernizer/plugin-architecture')!
  .getAnalysisRules();

for (const sourceFile of project.getSourceFiles()) {
  const context = ContextFactory.createAnalysisContext({
    sourceFile,
    project,
    api,
  });
  for (const rule of rules) {
    const results = await rule.analyze(context);
    results.forEach((r) => console.info(`${r.ruleId} ${r.filePath}:${r.line}: ${r.message}`));
  }
}
Copy

Single rule

import { LayerBoundaryViolationRule } from '@angular-modernizer/plugin-architecture';

const rule = new LayerBoundaryViolationRule(layers, { projectRoot });
const results = await rule.analyze(context);
Copy

Commands

pnpm --filter @angular-modernizer/plugin-architecture build
pnpm --filter @angular-modernizer/plugin-architecture test
Copy

Related Packages

• @angular-modernizer/plugin-system - plugin contracts
• @angular-modernizer/api - public API used by the rules
• @angular-modernizer/core - kernel and configuration
• @angular-modernizer/plugin-solid - SOLID analysis rules