architecture-linter 0.1.0

package/README.md

@@ -0,0 +1,686 @@
+# architecture-linter
+
+> Enforce architectural layer rules in TypeScript projects from the command line.
+
+`architecture-linter` reads a `.context.yml` configuration file and scans your
+TypeScript source tree for dependency violations — such as a controller importing
+a repository directly, bypassing the service layer.
+
+---
+
+## Quick start
+
+```bash
+npm install --save-dev architecture-linter
+npx architecture-linter init   # generate .context.yml from your folder structure
+npx architecture-linter scan   # check for violations
+```
+
+Expected output when a violation exists:
+
+```
+Scanning project...
+
+❌ Architecture violation detected
+
+   File:   controllers/orderController.ts
+   Import: repositories/orderRepository
+   Rule:   Controller cannot import Repository
+
+── Violations by layer ──────────────────
+   controller       1 violation(s)
+   service          0 violation(s)
+   repository       0 violation(s)
+
+Found 1 violation in 3 file(s) scanned.
+```
+
+---
+
+## Installation
+
+### As a local dev dependency (recommended)
+
+```bash
+npm install --save-dev architecture-linter
+```
+
+Add a script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint:arch": "architecture-linter scan"
+  }
+}
+```
+
+### Global install
+
+```bash
+npm install -g architecture-linter
+```
+
+---
+
+## Quick setup for a new project
+
+Run `init` to auto-generate a `.context.yml` by inspecting your folder structure.
+The command detects common layer names (`controller`, `service`, `repository`,
+`middleware`, etc.) from top-level and `src/` subdirectory names.
+
+```bash
+architecture-linter init
+```
+
+Then edit the generated file to add your constraints, and run:
+
+```bash
+architecture-linter scan
+```
+
+---
+
+## Framework presets
+
+Use a built-in preset to get a sensible starting configuration for popular
+architectural patterns. Declare it with the `extends` key in `.context.yml`:
+
+```yaml
+extends: nestjs
+```
+
+User-defined layers and rules always take precedence over preset defaults.
+
+| Preset | Layers |
+|---|---|
+| `nestjs` | module, controller, service, repository, guard, interceptor, pipe, decorator, dto, entity |
+| `clean-architecture` | entity, usecase, repository, infrastructure, interface |
+| `hexagonal` | domain, port, adapter, application, infrastructure |
+| `nextjs` | page, component, hook, lib, api, store, util |
+
+### Extending multiple presets
+
+```yaml
+extends:
+  - clean-architecture
+  - nestjs
+```
+
+### Overriding a preset rule
+
+```yaml
+extends: nestjs
+
+rules:
+  # Override the nestjs default — allow controllers to import repositories directly
+  controller:
+    cannot_import: []
+```
+
+---
+
+## Configuration reference
+
+Create a `.context.yml` in your project root (or pass `--context` to override).
+When `--context` is omitted, the linter walks up the directory tree until a
+`.context.yml` is found — just like ESLint.
+
+```yaml
+# Optional: extend a built-in preset
+extends: nestjs
+
+architecture:
+  layers:
+    - controller
+    - service
+    - repository
+
+rules:
+  # Blacklist: this layer must NOT import from any layer in the list.
+  controller:
+    cannot_import:
+      - repository
+
+  # Whitelist: this layer may ONLY import from layers in the list.
+  service:
+    can_only_import:
+      - repository
+
+  repository:
+    cannot_import: []
+
+# Glob patterns (project-relative) for files to skip entirely.
+exclude:
+  - "**/*.spec.ts"
+  - "**/*.test.ts"
+  - "**/__mocks__/**"
+
+# Manual path alias overrides (supplements tsconfig.json paths automatically).
+aliases:
+  "@repositories": "src/repositories"
+  "@services": "src/services"
+```
+
+### Rule options
+
+| Option | Type | Description |
+|---|---|---|
+| `cannot_import` | `string[]` | Blacklist — the layer must not import from any listed layer |
+| `can_only_import` | `string[]` | Whitelist — the layer may only import from listed layers |
+| `files` | `string` (glob) | Scope this rule to source files matching the pattern |
+
+`cannot_import` and `can_only_import` are mutually exclusive. Use one per layer rule.
+
+#### Scoping a rule to specific files
+
+```yaml
+rules:
+  controller:
+    files: "src/controllers/admin/**"
+    cannot_import:
+      - repository
+```
+
+### Path alias resolution
+
+The linter automatically reads `compilerOptions.paths` from your `tsconfig.json`
+and resolves aliased imports before checking rules. No extra config needed for
+standard TypeScript path aliases.
+
+For monorepos or non-standard setups, add manual overrides via the `aliases` key:
+
+```yaml
+aliases:
+  "@repositories": "src/repositories"
+```
+
+Manual aliases take precedence over any `tsconfig.json` entries with the same key.
+
+### Inline suppression with `arch-ignore`
+
+To suppress a single violation without removing the import, add an
+`// arch-ignore:` comment on the line immediately before the import:
+
+```ts
+// arch-ignore: controller cannot import repository
+import { OrderRepository } from '../repositories/orderRepository';
+```
+
+The hint must match the rule string (case-insensitive): `<sourceLayer> cannot import <targetLayer>`.
+
+---
+
+### How layer detection works
+
+The linter infers a file's layer from its **directory name**. Both singular and
+plural forms are recognised (including irregular plurals such as `repository` → `repositories`).
+
+| Path | Detected layer |
+|---|---|
+| `controllers/orderController.ts` | `controller` |
+| `services/orderService.ts` | `service` |
+| `repositories/orderRepository.ts` | `repository` |
+| `src/controllers/admin/ctrl.ts` | `controller` |
+
+---
+
+## CLI reference
+
+### `scan`
+
+```
+architecture-linter scan [options]
+
+Options:
+  -c, --context <path>   Path to the .context.yml file (auto-detected if omitted)
+  -p, --project <path>   Root directory of the project to scan   (default: .)
+  -f, --format <format>  Output format: text or json              (default: text)
+  -s, --strict           Report files not assigned to any layer
+  -q, --quiet            Suppress the "Scanning project..." banner
+  -e, --explain          Print why/impact/how-to-fix guidance per violation
+  -x, --fix              Show a suggested fix for each violation
+  -w, --watch            Watch for file changes and re-scan automatically
+  -h, --help             Display help
+```
+
+#### `--explain` — understand each violation
+
+```bash
+architecture-linter scan --explain
+```
+
+Adds three sections below each violation:
+- **Why this matters** — the architectural reason this rule exists
+- **Impact** — what goes wrong if the violation is left in place
+- **How to fix** — a concrete recommendation
+
+#### `--fix` — get a suggested fix
+
+```bash
+architecture-linter scan --fix
+```
+
+Prints a short actionable message per violation, e.g.:
+
+```
+🔧 Suggested fix
+   Instead of importing 'repository' directly, route through an allowed
+   intermediary layer: 'service'.
+```
+
+#### `--watch` — re-scan on file changes
+
+```bash
+architecture-linter scan --watch
+```
+
+Watches the project directory for `.ts` file changes and re-runs the scan
+automatically. Press `Ctrl+C` to stop.
+
+### `init`
+
+```
+architecture-linter init [options]
+
+Options:
+  -p, --project <path>   Root directory of the project  (default: .)
+```
+
+Generates a starter `.context.yml` by detecting layer names from directory
+structure. Fails safely if a `.context.yml` already exists.
+
+### `ci`
+
+```
+architecture-linter ci [options]
+
+Options:
+  --platform <platform>  CI platform to target: github  (default: github)
+  -p, --project <path>   Root directory of the project  (default: .)
+```
+
+Generates a ready-to-use CI workflow file. Currently supports GitHub Actions:
+
+```bash
+architecture-linter ci
+# Creates: .github/workflows/arch-lint.yml
+```
+
+Fails safely if the workflow file already exists.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | No violations found |
+| `1` | One or more violations found (or a fatal error occurred) |
+
+---
+
+## CI integration
+
+Run the linter on every push and pull request. The `ci` command generates this
+for you (`architecture-linter ci`), or add the step manually:
+
+```yaml
+# .github/workflows/arch-lint.yml
+name: Architecture Lint
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  arch-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+      - run: npm ci
+      - run: npx architecture-linter scan --strict
+```
+
+---
+
+## JSON output
+
+```bash
+architecture-linter scan --format json
+architecture-linter scan --format json --fix --explain
+```
+
+```json
+{
+  "filesScanned": 3,
+  "violations": [
+    {
+      "file": "controllers/orderController.ts",
+      "importPath": "repositories/orderRepository",
+      "rawSpecifier": "../repositories/orderRepository",
+      "sourceLayer": "controller",
+      "targetLayer": "repository",
+      "rule": "Controller cannot import Repository",
+      "fix": "Instead of importing 'repository' directly, route through an allowed intermediary layer: 'service'.",
+      "explanation": {
+        "why": "...",
+        "impact": "...",
+        "fix": "..."
+      }
+    }
+  ],
+  "unclassifiedFiles": [],
+  "violationsByLayer": {
+    "controller": 1,
+    "service": 0,
+    "repository": 0
+  }
+}
+```
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run directly with ts-node (no build required)
+npx ts-node src/cli.ts scan --context examples/sample.context.yml --project examples/sample-project
+
+# Build to dist/
+npm run build
+
+# Run the full test suite
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Clean build artefacts
+npm run clean
+```
+
+---
+
+## Project structure
+
+```
+architecture-linter/
+├── src/
+│   ├── cli.ts               # Commander-based CLI entry point
+│   ├── contextParser.ts     # Loads and validates .context.yml; walks up directory tree
+│   ├── dependencyScanner.ts # Walks .ts files and extracts imports via ts-morph
+│   ├── ruleEngine.ts        # Matches imports against rules; builds violations
+│   ├── aliasResolver.ts     # Resolves tsconfig.json path aliases
+│   ├── presets.ts           # Built-in framework presets
+│   ├── explainer.ts         # Why/impact/fix guidance for --explain
+│   └── types.ts             # Shared TypeScript interfaces
+│
+├── src/__tests__/           # Jest test suite (105 tests)
+│
+├── examples/
+│   ├── sample.context.yml         # Example rule configuration
+│   ├── sample-project/            # ❌ intentional violation for demo
+│   ├── alias-test/                # Demo of path alias resolution
+│   └── preset-test/               # Demo of framework presets
+│
+├── .github/workflows/ci.yml  # Runs tests on every push/PR
+├── jest.config.js
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+---
+
+## How it works
+
+1. **Parse config** — `contextParser` loads `.context.yml`, merges any preset
+   declared via `extends`, validates required fields, and walks up the directory
+   tree when no explicit path is provided.
+2. **Scan files** — `dependencyScanner` uses `fast-glob` to find every `.ts`
+   file (respecting `exclude` patterns) and `ts-morph` to parse import
+   declarations. Path aliases are resolved via `aliasResolver` before rules are
+   applied. Each import is checked for a preceding `// arch-ignore:` comment.
+3. **Check rules** — `ruleEngine` evaluates `cannot_import` / `can_only_import`
+   rules against each import. Violations are collected with optional fix
+   suggestions and layer-level counts.
+4. **Report** — results are printed as human-readable text (with colour) or
+   machine-readable JSON. The process exits `0` for clean, `1` for violations.
+3. **Apply rules** — `ruleEngine` maps each file and resolved import to an
+   architectural layer, then evaluates `cannot_import` (blacklist) and
+   `can_only_import` (whitelist) rules. Per-rule `files` glob scoping is
+   applied via `minimatch`.
+4. **Report** — The CLI prints every violation with the file, import path, and
+   rule broken. A per-layer summary is shown at the end. `--format json` emits
+   machine-readable output.
+
+---
+
+## Roadmap (post-MVP)
+
+- `--fix` flag to suggest corrected import paths
+- SARIF output format for GitHub Advanced Security integration
+- Watch mode (`--watch`)
+- Support for TypeScript path alias resolution (`@app/repositories`)
+
+---
+
+## License
+
+MIT
+
+
+`architecture-linter` reads a `.context.yml` configuration file and scans your
+TypeScript source tree for dependency violations — such as a controller importing
+a repository directly, bypassing the service layer.
+
+---
+
+## Quick start
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Build
+npm run build
+
+# 3. Scan the bundled example project
+node dist/cli.js scan \
+  --context examples/sample.context.yml \
+  --project examples/sample-project
+```
+
+Expected output:
+
+```
+Scanning project...
+
+❌ Architecture violation detected
+
+   File:    controllers/orderController.ts
+   Import:  repositories/orderRepository
+   Rule:    Controller cannot import Repository
+
+Found 1 violation in 3 file(s) scanned.
+```
+
+---
+
+## Installation
+
+### As a local dev dependency
+
+```bash
+npm install --save-dev architecture-linter
+```
+
+Then add a script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint:arch": "architecture-linter scan"
+  }
+}
+```
+
+### Global install
+
+```bash
+npm install -g architecture-linter
+```
+
+---
+
+## Configuration
+
+Create a `.context.yml` file in your project root (or pass `--context` to point
+to a different path).
+
+```yaml
+architecture:
+  layers:
+    - controller
+    - service
+    - repository
+
+rules:
+  controller:
+    cannot_import:
+      - repository   # Controllers must go through the service layer
+
+  service:
+    cannot_import: []
+
+  repository:
+    cannot_import: []
+```
+
+### How layer detection works
+
+The linter infers a file's layer from its **directory name**. A file inside a
+directory called `controllers/` or `controller/` is automatically assigned to
+the `controller` layer. Both singular and plural forms are recognised.
+
+| Path | Detected layer |
+|---|---|
+| `controllers/orderController.ts` | `controller` |
+| `services/orderService.ts` | `service` |
+| `repositories/orderRepository.ts` | `repository` |
+
+The same logic applies to import paths: a relative import that resolves into a
+`repositories/` directory is treated as a `repository`-layer import.
+
+---
+
+## CLI reference
+
+```
+architecture-linter scan [options]
+
+Options:
+  -c, --context <path>   Path to the .context.yml file  (default: .context.yml)
+  -p, --project <path>   Root directory of the project  (default: .)
+  -V, --version          Print version number
+  -h, --help             Display help
+```
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | No violations found |
+| `1` | One or more violations found (or a fatal error occurred) |
+
+This makes the tool suitable for use in CI pipelines:
+
+```yaml
+# .github/workflows/ci.yml (example)
+- name: Architecture lint
+  run: npx architecture-linter scan
+```
+
+---
+
+## Development
+
+```bash
+# Run directly with ts-node (no build step required)
+npx ts-node src/cli.ts scan --context examples/sample.context.yml --project examples/sample-project
+
+# Build to dist/
+npm run build
+
+# Run the compiled output
+node dist/cli.js scan --context examples/sample.context.yml --project examples/sample-project
+
+# Clean build artefacts
+npm run clean
+```
+
+---
+
+## Project structure
+
+```
+architecture-linter/
+├── src/
+│   ├── cli.ts               # Commander-based CLI entry point
+│   ├── contextParser.ts     # Loads and validates .context.yml
+│   ├── dependencyScanner.ts # Walks .ts files and extracts imports via ts-morph
+│   ├── ruleEngine.ts        # Matches imports against rules and returns violations
+│   └── types.ts             # Shared TypeScript interfaces
+│
+├── examples/
+│   ├── sample.context.yml                        # Example rule configuration
+│   └── sample-project/
+│       ├── controllers/orderController.ts        # ❌ contains an intentional violation
+│       ├── services/orderService.ts
+│       └── repositories/orderRepository.ts
+│
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+---
+
+## How it works
+
+1. **Parse config** — `contextParser` loads `.context.yml` using `js-yaml` and
+   validates the required fields.
+2. **Scan files** — `dependencyScanner` uses `fast-glob` to find every `.ts`
+   file in the project and `ts-morph` to parse its import declarations.
+   Relative imports are resolved to project-relative paths.
+3. **Apply rules** — `ruleEngine` maps each file and each resolved import path
+   to an architectural layer, then checks the `cannot_import` rules.
+4. **Report** — The CLI prints every violation with the offending file, the
+   resolved import path, and the rule that was broken.
+
+---
+
+## Roadmap (post-MVP)
+
+- `--fix` flag to suggest corrected import paths
+- JSON / SARIF output format for CI integration
+- Wildcard layer patterns (`src/*/controllers/**`)
+- Support for path alias resolution (`@app/repositories`)
+- Watch mode
+
+---
+
+## License
+
+MIT

package/dist/aliasResolver.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A resolved alias map where each key is an alias prefix (e.g. '@repositories')
+ * and each value is the absolute path to the corresponding directory on disk.
+ */
+export interface AliasMap {
+    [prefix: string]: string;
+}
+/**
+ * Reads tsconfig.json from the project root and extracts compilerOptions.paths
+ * entries, resolving them relative to compilerOptions.baseUrl (or the project root).
+ *
+ * Handles tsconfig files that contain // line comments (which TypeScript allows).
+ *
+ * Returns an empty map if tsconfig.json is absent or cannot be parsed.
+ */
+export declare function loadTsConfigAliases(projectDir: string): AliasMap;
+/**
+ * Merges tsconfig-derived aliases with any manual aliases declared in .context.yml.
+ * Manual aliases take precedence over tsconfig aliases.
+ *
+ * @param tsconfigAliases  Aliases loaded from tsconfig.json
+ * @param configAliases    Aliases from the `aliases:` field in .context.yml (project-relative dirs)
+ * @param projectDir       Absolute path to the project root (used to resolve configAliases)
+ */
+export declare function mergeAliases(tsconfigAliases: AliasMap, configAliases: Record<string, string> | undefined, projectDir: string): AliasMap;
+/**
+ * Attempts to resolve a bare (non-relative) import specifier using the alias map.
+ *
+ * Returns a project-relative forward-slash path on success, or null if the specifier
+ * does not match any known alias (e.g. it's a node_modules package).
+ *
+ * @param specifier   The raw import string (e.g. '@repositories/orderRepo')
+ * @param aliases     The merged alias map
+ * @param projectDir  Absolute path to the project root
+ */
+export declare function resolveAlias(specifier: string, aliases: AliasMap, projectDir: string): string | null;
+//# sourceMappingURL=aliasResolver.d.ts.map

package/dist/aliasResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliasResolver.d.ts","sourceRoot":"","sources":["../src/aliasResolver.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,CA0ChE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,eAAe,EAAE,QAAQ,EACzB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACjD,UAAU,EAAE,MAAM,GACjB,QAAQ,CAUV;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,QAAQ,EACjB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CASf"}