stratifyjs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Scott Mikula
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE

package/README.md

@@ -0,0 +1,354 @@
+# Stratify
+
+Enforce architectural layer boundaries in monorepos. Catches invalid cross-layer dependencies at build time by analyzing `workspace:` protocol imports in `package.json` files.
+
+## Installation
+
+```bash
+npm install stratifyjs
+# or
+yarn add stratifyjs
+```
+
+For CLI-only usage you can install globally:
+
+```bash
+npm install -g stratifyjs
+```
+
+## Quick Start
+
+1. Add a `"layer"` field to each workspace `package.json`:
+
+```json
+{
+    "name": "my-feature",
+    "layer": "features",
+    "dependencies": {
+        "my-core-lib": "workspace:*"
+    }
+}
+```
+
+2. Create a `stratify.config.json` at your workspace root:
+
+```json
+{
+    "layers": {
+        "features": {
+            "description": "Feature packages",
+            "allowedDependencies": ["core", "shared"]
+        },
+        "core": {
+            "description": "Core business logic",
+            "allowedDependencies": ["shared"]
+        },
+        "shared": {
+            "description": "Shared utilities",
+            "allowedDependencies": []
+        }
+    }
+}
+```
+
+3. Run:
+
+```bash
+stratify --config stratify.config.json
+```
+
+## CLI Usage
+
+```
+stratify [options]
+```
+
+| Option                | Default                | Description                                          |
+| --------------------- | ---------------------- | ---------------------------------------------------- |
+| `-c, --config <path>` | `stratify.config.json`    | Path to the layer config file (relative to root)     |
+| `-r, --root <path>`   | `process.cwd()`        | Workspace root directory                             |
+| `-m, --mode <mode>`   | Config value or `warn` | Override enforcement mode: `error`, `warn`, or `off` |
+| `--format <type>`     | `console`              | Output format: `console` or `json`                   |
+| `-V, --version`       |                        | Print version                                        |
+| `-h, --help`          |                        | Print help                                           |
+
+### Examples
+
+```bash
+# Basic check with defaults
+stratify
+
+# Explicit config and root
+stratify --config stratify.config.json --root /path/to/monorepo
+
+# Fail CI on violations
+stratify --mode error
+
+# Machine-readable output
+stratify --format json
+
+# Combine options
+stratify -c stratify.config.json -r ../.. -m error --format console
+```
+
+### Exit Codes
+
+| Code | Meaning                                                         |
+| ---- | --------------------------------------------------------------- |
+| `0`  | No violations, or mode is `warn`/`off`                          |
+| `1`  | Violations found and mode is `error`, or a fatal error occurred |
+
+## Programmatic API
+
+The library API is available for custom tooling, editor integrations, or CI pipelines.
+
+### `enforceLayersAsync(options?)`
+
+Run the full enforcement pipeline: load config → discover packages → validate → report.
+
+```typescript
+import { enforceLayersAsync, formatResults } from 'stratifyjs';
+
+const result = await enforceLayersAsync({
+    workspaceRoot: '/path/to/monorepo',
+    configPath: 'stratify.config.json',
+    mode: 'error', // optional override
+});
+
+if (!result.success) {
+    console.error('Error:', result.error);
+    process.exit(1);
+}
+
+const { violations, packages, config, report, warnings } = result.value;
+console.log(`Checked ${packages.length} packages, found ${violations.length} violations`);
+
+// Format for display
+const output = formatResults(result.value, 'console', 'warn');
+console.log(output);
+```
+
+### `validateConfig(raw)`
+
+Validate a raw config object without reading from disk. Useful for editor integrations.
+
+```typescript
+import { validateConfig } from 'stratifyjs';
+
+const result = validateConfig({
+    layers: {
+        core: { allowedDependencies: [] },
+        features: { allowedDependencies: ['core'] },
+    },
+});
+
+if (result.success) {
+    console.log('Valid config:', result.value);
+} else {
+    console.error('Invalid:', result.error);
+}
+```
+
+### `formatResults(result, format, mode)`
+
+Format an `EnforceLayersResult` as a string for display.
+
+```typescript
+import { formatResults } from 'stratifyjs';
+
+const consoleOutput = formatResults(result.value, 'console', 'warn');
+const jsonOutput = formatResults(result.value, 'json', 'error');
+```
+
+## Config File Format
+
+The config file (default: `stratify.config.json`) is a JSON object with three sections:
+
+```json
+{
+  "layers": { ... },
+  "enforcement": { ... },
+  "workspaces": { ... }
+}
+```
+
+### `layers` (required)
+
+A map of layer names to their definitions. Each layer must specify which other layers it is allowed to depend on.
+
+```json
+{
+    "layers": {
+        "adapters": {
+            "description": "I/O and external integrations",
+            "allowedDependencies": ["core", "types"]
+        },
+        "core": {
+            "description": "Pure business logic",
+            "allowedDependencies": ["types"]
+        },
+        "types": {
+            "description": "Shared type definitions",
+            "allowedDependencies": []
+        }
+    }
+}
+```
+
+| Field                 | Type       | Required | Description                                                          |
+| --------------------- | ---------- | -------- | -------------------------------------------------------------------- |
+| `description`         | `string`   | No       | Human-readable description of the layer's purpose                    |
+| `allowedDependencies` | `string[]` | **Yes**  | Layer names this layer may depend on. Use `"*"` to allow all layers. |
+
+### `enforcement` (optional)
+
+Controls how violations are reported.
+
+```json
+{
+    "enforcement": {
+        "mode": "error"
+    }
+}
+```
+
+| Field  | Type                         | Default  | Description                                                               |
+| ------ | ---------------------------- | -------- | ------------------------------------------------------------------------- |
+| `mode` | `"error" \| "warn" \| "off"` | `"warn"` | `error` = non-zero exit on violations; `warn` = report only; `off` = skip |
+
+### `workspaces` (optional)
+
+Controls which packages are discovered for validation.
+
+```json
+{
+    "workspaces": {
+        "patterns": ["packages/**/*", "shared/**/*"]
+    }
+}
+```
+
+| Field      | Type       | Default             | Description                                                                     |
+| ---------- | ---------- | ------------------- | ------------------------------------------------------------------------------- |
+| `patterns` | `string[]` | `["packages/**/*"]` | Glob patterns to locate workspace packages (each must contain a `package.json`) |
+
+Ignored paths (hardcoded): `**/node_modules/**`, `**/lib/**`, `**/dist/**`.
+
+## Layer Definition Reference
+
+### Package Assignment
+
+Each workspace package declares its layer via the `"layer"` field in `package.json`:
+
+```json
+{
+    "name": "my-package",
+    "version": "1.0.0",
+    "layer": "core"
+}
+```
+
+Packages missing the `"layer"` field produce a `missing-layer` violation.
+
+### Dependency Detection
+
+Only `workspace:` protocol dependencies are checked, across all three dependency fields:
+
+-   `dependencies`
+-   `devDependencies`
+-   `peerDependencies`
+
+External (npm registry) dependencies are ignored — layers only govern internal monorepo boundaries.
+
+### Violation Types
+
+| Type                 | Description                                                                    |
+| -------------------- | ------------------------------------------------------------------------------ |
+| `missing-layer`      | Package has no `"layer"` field in its `package.json`                           |
+| `unknown-layer`      | Package declares a layer not defined in the config                             |
+| `invalid-dependency` | Package depends on another package whose layer is not in `allowedDependencies` |
+
+### Wildcard Dependencies
+
+Use `"*"` to allow a layer to depend on any other layer:
+
+```json
+{
+    "layers": {
+        "app": {
+            "description": "Application entry points — can use anything",
+            "allowedDependencies": ["*"]
+        }
+    }
+}
+```
+
+### Full Config Example
+
+```json
+{
+    "layers": {
+        "app": {
+            "description": "Application entry points",
+            "allowedDependencies": ["features", "core", "shared"]
+        },
+        "features": {
+            "description": "Feature modules",
+            "allowedDependencies": ["core", "shared"]
+        },
+        "core": {
+            "description": "Core business logic",
+            "allowedDependencies": ["shared"]
+        },
+        "shared": {
+            "description": "Shared utilities and types",
+            "allowedDependencies": []
+        }
+    },
+    "enforcement": {
+        "mode": "error"
+    },
+    "workspaces": {
+        "patterns": ["packages/**/*", "libs/**/*"]
+    }
+}
+```
+
+## CI Integration
+
+Add to your CI pipeline to enforce boundaries on every PR:
+
+```yaml
+# GitHub Actions
+- name: Enforce layers
+  run: npx stratify --config stratify.config.json --mode error
+```
+
+```yaml
+# Azure Pipelines
+- script: npx stratify --config stratify.config.json --mode error
+  displayName: 'Enforce layer boundaries'
+```
+
+## Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Run tests
+yarn test
+
+# Run tests in watch mode
+yarn test:watch
+
+# Build (compile TypeScript → lib/)
+yarn build
+
+# Type-check without emitting
+yarn typecheck
+```
+
+## License
+
+MIT

package/lib/adapters/config-file-loader.d.ts

@@ -0,0 +1,8 @@
+import type { ResolvedConfig } from '../types/types.js';
+import type { ConfigError } from '../core/errors.js';
+import type { Result } from '../core/result.js';
+/**
+ * Load a layer config file from disk, validate it, and apply defaults.
+ * I/O adapter — reads from the file system.
+ */
+export declare function loadConfigFromFile(workspaceRoot: string, configPath: string): Promise<Result<ResolvedConfig, ConfigError>>;

package/lib/adapters/config-file-loader.js

@@ -0,0 +1,55 @@
+import { readFile, access } from 'fs/promises';
+import { resolve } from 'path';
+import { ok, err } from '../core/result.js';
+import { validateConfigSchema } from '../core/config-schema.js';
+import { applyDefaults } from '../core/config-defaults.js';
+/**
+ * Load a layer config file from disk, validate it, and apply defaults.
+ * I/O adapter — reads from the file system.
+ */
+export async function loadConfigFromFile(workspaceRoot, configPath) {
+    const fullPath = resolve(workspaceRoot, configPath);
+    // Check file exists
+    try {
+        await access(fullPath);
+    }
+    catch {
+        return err({
+            type: 'config-not-found',
+            message: `Config file not found: ${fullPath}`,
+            path: fullPath,
+        });
+    }
+    // Read file
+    let content;
+    try {
+        content = await readFile(fullPath, 'utf-8');
+    }
+    catch (error) {
+        return err({
+            type: 'config-read-error',
+            message: error instanceof Error ? error.message : String(error),
+            path: fullPath,
+            cause: error,
+        });
+    }
+    // Parse JSON
+    let rawConfig;
+    try {
+        rawConfig = JSON.parse(content);
+    }
+    catch (error) {
+        return err({
+            type: 'config-parse-error',
+            message: error instanceof Error ? error.message : String(error),
+            path: fullPath,
+            cause: error,
+        });
+    }
+    // Validate schema
+    const validated = validateConfigSchema(rawConfig);
+    if (!validated.success) {
+        return validated;
+    }
+    return ok(applyDefaults(validated.value));
+}

package/lib/adapters/file-system-discovery.d.ts

@@ -0,0 +1,22 @@
+import type { Package, WorkspaceConfig } from '../types/types.js';
+import type { DiscoveryError } from '../core/errors.js';
+import type { Result } from '../core/result.js';
+/**
+ * Non-fatal warning produced during discovery.
+ */
+export interface DiscoveryWarning {
+    path: string;
+    message: string;
+}
+/**
+ * Successful discovery result containing packages and any non-fatal warnings.
+ */
+export interface DiscoveryResult {
+    packages: Package[];
+    warnings: DiscoveryWarning[];
+}
+/**
+ * Discover all packages in the workspace by globbing for package.json files.
+ * I/O adapter — reads from the file system using glob + readFile.
+ */
+export declare function discoverPackages(root: string, config: WorkspaceConfig, ignore?: string[]): Promise<Result<DiscoveryResult, DiscoveryError>>;

package/lib/adapters/file-system-discovery.js

@@ -0,0 +1,61 @@
+import { readFile } from 'fs/promises';
+import { resolve } from 'path';
+import { glob } from 'glob';
+import { ok, err } from '../core/result.js';
+import { parsePackageJson } from '../core/package-parser.js';
+const DEFAULT_IGNORE = ['**/node_modules/**', '**/lib/**', '**/dist/**'];
+/**
+ * Discover all packages in the workspace by globbing for package.json files.
+ * I/O adapter — reads from the file system using glob + readFile.
+ */
+export async function discoverPackages(root, config, ignore = DEFAULT_IGNORE) {
+    const allPaths = [];
+    for (const pattern of config.patterns) {
+        try {
+            const paths = await glob(`${pattern}/package.json`, {
+                cwd: root,
+                ignore,
+            });
+            allPaths.push(...paths);
+        }
+        catch (error) {
+            return err({
+                type: 'glob-failed',
+                message: error instanceof Error ? error.message : String(error),
+                pattern,
+                cause: error,
+            });
+        }
+    }
+    const uniquePaths = [...new Set(allPaths)];
+    const settledPackages = await Promise.allSettled(uniquePaths.map(async (relativePath) => {
+        const fullPath = resolve(root, relativePath);
+        const content = await readFile(fullPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        return { relativePath, fullPath, parsed };
+    }));
+    const packages = [];
+    const warnings = [];
+    for (let i = 0; i < settledPackages.length; i++) {
+        const entry = settledPackages[i];
+        const relativePath = uniquePaths[i];
+        const fullPath = resolve(root, relativePath);
+        if (entry.status === 'rejected') {
+            const reason = entry.reason;
+            warnings.push({
+                path: fullPath,
+                message: reason instanceof Error ? reason.message : String(reason),
+            });
+            continue;
+        }
+        const { parsed } = entry.value;
+        const result = parsePackageJson(parsed, relativePath);
+        if (result.success) {
+            packages.push(result.value);
+        }
+        else {
+            warnings.push({ path: fullPath, message: result.error.message });
+        }
+    }
+    return ok({ packages, warnings });
+}

package/lib/api/api.d.ts

@@ -0,0 +1,42 @@
+import type { ResolvedConfig, Violation, Package, EnforcementConfig } from '../types/types.js';
+import type { LayerError, ConfigError } from '../core/errors.js';
+import type { Result } from '../core/result.js';
+import { type DiscoveryWarning } from '../adapters/file-system-discovery.js';
+import { type ValidationReport } from '../core/report-builder.js';
+/**
+ * Options for the enforce-layers library API.
+ */
+export interface EnforceLayersOptions {
+    /** Workspace root directory. Defaults to process.cwd(). */
+    workspaceRoot?: string;
+    /** Path to the config file, relative to workspaceRoot. */
+    configPath?: string;
+    /** Provide a pre-built config directly, skipping file loading. */
+    config?: ResolvedConfig;
+    /** Override the enforcement mode from config. */
+    mode?: EnforcementConfig['mode'];
+}
+/**
+ * Result of running layer enforcement.
+ */
+export interface EnforceLayersResult {
+    violations: Violation[];
+    packages: Package[];
+    config: ResolvedConfig;
+    report: ValidationReport;
+    warnings: DiscoveryWarning[];
+}
+/**
+ * Run layer enforcement programmatically.
+ * Returns a Result
+ */
+export declare function enforceLayersAsync(options?: EnforceLayersOptions): Promise<Result<EnforceLayersResult, LayerError>>;
+/**
+ * Validate a raw config object without reading from a file.
+ * Useful for editor integrations or programmatic config construction.
+ */
+export declare function validateConfig(raw: unknown): Result<ResolvedConfig, ConfigError>;
+/**
+ * Format an enforcement result for display.
+ */
+export declare function formatResults(result: EnforceLayersResult, format?: 'console' | 'json', mode?: EnforcementConfig['mode']): string;

package/lib/api/api.js

@@ -0,0 +1,75 @@
+import { resolve } from 'path';
+import { ok } from '../core/result.js';
+import { validateConfigSchema } from '../core/config-schema.js';
+import { applyDefaults } from '../core/config-defaults.js';
+import { validatePackages } from '../core/validation.js';
+import { loadConfigFromFile } from '../adapters/config-file-loader.js';
+import { discoverPackages } from '../adapters/file-system-discovery.js';
+import { buildReport } from '../core/report-builder.js';
+import { formatConsole } from '../core/formatters/console-formatter.js';
+import { formatJson } from '../core/formatters/json-formatter.js';
+/**
+ * Run layer enforcement programmatically.
+ * Returns a Result
+ */
+export async function enforceLayersAsync(options = {}) {
+    const startTime = performance.now();
+    const workspaceRoot = resolve(options.workspaceRoot ?? process.cwd());
+    // Resolve config
+    let config;
+    if (options.config) {
+        config = options.config;
+    }
+    else {
+        const configPath = options.configPath ?? 'stratify.config.json';
+        const configResult = await loadConfigFromFile(workspaceRoot, configPath);
+        if (!configResult.success) {
+            return configResult;
+        }
+        config = configResult.value;
+    }
+    // Apply mode override
+    if (options.mode) {
+        config = {
+            ...config,
+            enforcement: { ...config.enforcement, mode: options.mode },
+        };
+    }
+    // Discover packages
+    const discoveryResult = await discoverPackages(workspaceRoot, config.workspaces);
+    if (!discoveryResult.success) {
+        return discoveryResult;
+    }
+    const { packages, warnings } = discoveryResult.value;
+    // Validate packages against config
+    const violations = validatePackages(packages, config);
+    const duration = performance.now() - startTime;
+    const report = buildReport(violations, {
+        totalPackages: packages.length,
+        duration,
+    });
+    return ok({ violations, packages, config, report, warnings });
+}
+/**
+ * Validate a raw config object without reading from a file.
+ * Useful for editor integrations or programmatic config construction.
+ */
+export function validateConfig(raw) {
+    const validated = validateConfigSchema(raw);
+    if (!validated.success) {
+        return validated;
+    }
+    return ok(applyDefaults(validated.value));
+}
+/**
+ * Format an enforcement result for display.
+ */
+export function formatResults(result, format = 'console', mode = 'warn') {
+    switch (format) {
+        case 'json':
+            return formatJson(result.report);
+        case 'console':
+        default:
+            return formatConsole(result.report, mode);
+    }
+}

package/lib/api/index.d.ts

@@ -0,0 +1,15 @@
+export { enforceLayersAsync, validateConfig, formatResults } from './api.js';
+export type { EnforceLayersOptions, EnforceLayersResult } from './api.js';
+export type { Package, LayerConfig, LayerDefinition, LayerMap, ResolvedConfig, EnforcementConfig, WorkspaceConfig, Violation, ViolationType, } from '../types/types.js';
+export type { LayerError, ConfigError, DiscoveryError } from '../core/errors.js';
+export { formatLayerError } from '../core/errors.js';
+export type { Result } from '../core/result.js';
+export { ok, err, isOk, isErr } from '../core/result.js';
+export type { ValidationReport } from '../core/report-builder.js';
+export { buildReport } from '../core/report-builder.js';
+export { validatePackages } from '../core/validation.js';
+export { validateConfigSchema } from '../core/config-schema.js';
+export { applyDefaults } from '../core/config-defaults.js';
+export { parsePackageJson, extractWorkspaceDependencies } from '../core/package-parser.js';
+export { formatConsole } from '../core/formatters/console-formatter.js';
+export { formatJson } from '../core/formatters/json-formatter.js';

package/lib/api/index.js

@@ -0,0 +1,12 @@
+// Main API
+export { enforceLayersAsync, validateConfig, formatResults } from './api.js';
+export { formatLayerError } from '../core/errors.js';
+export { ok, err, isOk, isErr } from '../core/result.js';
+export { buildReport } from '../core/report-builder.js';
+// Advanced: individual components for custom pipelines
+export { validatePackages } from '../core/validation.js';
+export { validateConfigSchema } from '../core/config-schema.js';
+export { applyDefaults } from '../core/config-defaults.js';
+export { parsePackageJson, extractWorkspaceDependencies } from '../core/package-parser.js';
+export { formatConsole } from '../core/formatters/console-formatter.js';
+export { formatJson } from '../core/formatters/json-formatter.js';

package/lib/cli/command-handler.d.ts

@@ -0,0 +1,6 @@
+import type { CliOptions } from './options.js';
+/**
+ * Handle the main enforce command.
+ * Returns an exit code: 0 = success, 1 = failure.
+ */
+export declare function handleEnforceCommand(options: CliOptions): Promise<number>;