stratifyjs 1.0.0

package/lib/cli/command-handler.js

@@ -0,0 +1,50 @@
+import { resolve } from 'path';
+import { enforceLayersAsync, formatResults } from '../api/api.js';
+import { formatLayerError } from '../api/index.js';
+import { toLibraryOptions } from './options.js';
+import { logInfo, logSuccess, logWarning, logError, logGray, logPlain } from './output-helpers.js';
+/**
+ * Handle the main enforce command.
+ * Returns an exit code: 0 = success, 1 = failure.
+ */
+export async function handleEnforceCommand(options) {
+    const workspaceRoot = resolve(options.root);
+    const configPath = resolve(workspaceRoot, options.config);
+    logInfo('🔍 Enforce Layers\n');
+    logGray(`Root: ${workspaceRoot}`);
+    logGray(`Config: ${configPath}\n`);
+    const result = await enforceLayersAsync(toLibraryOptions(options));
+    if (!result.success) {
+        logError(`❌ ${formatLayerError(result.error)}`);
+        return 1;
+    }
+    const { config, packages, violations, warnings } = result.value;
+    const effectiveMode = options.mode ?? config.enforcement.mode;
+    logSuccess(`✅ Loaded config with ${Object.keys(config.layers).length} layers`);
+    logGray(`   Mode: ${effectiveMode}\n`);
+    logSuccess(`✅ Discovered ${packages.length} packages\n`);
+    if (warnings.length > 0) {
+        logWarning(`⚠️  ${warnings.length} warnings\n`);
+        for (const warning of warnings) {
+            logWarning(`   • ${warning.path}: ${warning.message}`);
+        }
+        logPlain('');
+    }
+    // Get plain text report from formatter, add colors here
+    const plainReport = formatResults(result.value, options.format, effectiveMode);
+    if (options.format === 'json') {
+        logPlain(plainReport);
+    }
+    else {
+        if (violations.length > 0) {
+            logError(plainReport);
+        }
+        else {
+            logSuccess(plainReport);
+        }
+    }
+    if (effectiveMode === 'error' && violations.length > 0) {
+        return 1;
+    }
+    return 0;
+}

package/lib/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/cli/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import { createRequire } from 'module';
+import { parseCliOptions } from './options.js';
+import { handleEnforceCommand } from './command-handler.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../../package.json');
+program
+    .name('stratifyjs')
+    .description('Enforce package layering rules in monorepos')
+    .version(version)
+    .option('-c, --config <path>', 'Path to layer config file', 'stratify.config.json')
+    .option('-r, --root <path>', 'Workspace root directory', process.cwd())
+    .option('-m, --mode <mode>', 'Override enforcement mode (error|warn|off)')
+    .option('--format <type>', 'Output format (console|json)', 'console')
+    .parse(process.argv);
+const options = parseCliOptions(program.opts());
+handleEnforceCommand(options)
+    .then(code => process.exit(code))
+    .catch(error => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/lib/cli/options.d.ts

@@ -0,0 +1,18 @@
+import type { EnforceLayersOptions } from '../api/api.js';
+/**
+ * Parsed CLI options.
+ */
+export interface CliOptions {
+    config: string;
+    root: string;
+    mode?: 'error' | 'warn' | 'off';
+    format: 'console' | 'json';
+}
+/**
+ * Convert raw commander output into typed CliOptions.
+ */
+export declare function parseCliOptions(raw: Record<string, unknown>): CliOptions;
+/**
+ * Convert CLI options to library options.
+ */
+export declare function toLibraryOptions(cli: CliOptions): EnforceLayersOptions;

package/lib/cli/options.js

@@ -0,0 +1,21 @@
+/**
+ * Convert raw commander output into typed CliOptions.
+ */
+export function parseCliOptions(raw) {
+    return {
+        config: raw.config ?? 'stratify.config.json',
+        root: raw.root ?? process.cwd(),
+        mode: raw.mode,
+        format: raw.format ?? 'console',
+    };
+}
+/**
+ * Convert CLI options to library options.
+ */
+export function toLibraryOptions(cli) {
+    return {
+        workspaceRoot: cli.root,
+        configPath: cli.config,
+        mode: cli.mode,
+    };
+}

package/lib/cli/output-helpers.d.ts

@@ -0,0 +1,9 @@
+/**
+ * CLI-specific output helpers with colored terminal formatting.
+ */
+export declare function logInfo(message: string): void;
+export declare function logSuccess(message: string): void;
+export declare function logWarning(message: string): void;
+export declare function logError(message: string): void;
+export declare function logGray(message: string): void;
+export declare function logPlain(message: string): void;

package/lib/cli/output-helpers.js

@@ -0,0 +1,22 @@
+import pc from 'picocolors';
+/**
+ * CLI-specific output helpers with colored terminal formatting.
+ */
+export function logInfo(message) {
+    console.log(pc.blue(message));
+}
+export function logSuccess(message) {
+    console.log(pc.green(message));
+}
+export function logWarning(message) {
+    console.log(pc.yellow(message));
+}
+export function logError(message) {
+    console.error(pc.red(message));
+}
+export function logGray(message) {
+    console.log(pc.gray(message));
+}
+export function logPlain(message) {
+    console.log(message);
+}

package/lib/core/config-defaults.d.ts

@@ -0,0 +1,7 @@
+import type { LayerConfig, ResolvedConfig, EnforcementConfig, WorkspaceConfig } from '../types/types.js';
+export declare const DEFAULT_ENFORCEMENT: EnforcementConfig;
+export declare const DEFAULT_WORKSPACES: WorkspaceConfig;
+/**
+ * Apply defaults to a validated LayerConfig, producing a fully resolved config.
+ */
+export declare function applyDefaults(config: LayerConfig): ResolvedConfig;

package/lib/core/config-defaults.js

@@ -0,0 +1,22 @@
+export const DEFAULT_ENFORCEMENT = {
+    mode: 'warn',
+};
+export const DEFAULT_WORKSPACES = {
+    patterns: ['packages/**/*'],
+};
+/**
+ * Apply defaults to a validated LayerConfig, producing a fully resolved config.
+ */
+export function applyDefaults(config) {
+    return {
+        layers: config.layers,
+        enforcement: {
+            ...DEFAULT_ENFORCEMENT,
+            ...config.enforcement,
+        },
+        workspaces: {
+            ...DEFAULT_WORKSPACES,
+            ...config.workspaces,
+        },
+    };
+}

package/lib/core/config-schema.d.ts

@@ -0,0 +1,11 @@
+import type { LayerConfig, LayerDefinition } from '../types/types.js';
+import type { ConfigError } from './errors.js';
+import type { Result } from './result.js';
+/**
+ * Validate that a raw parsed object conforms to the LayerConfig schema.
+ */
+export declare function validateConfigSchema(raw: unknown): Result<LayerConfig, ConfigError>;
+/**
+ * Validate a single layer definition.
+ */
+export declare function validateLayerDefinition(name: string, raw: unknown): Result<LayerDefinition, ConfigError>;

package/lib/core/config-schema.js

@@ -0,0 +1,102 @@
+import { ok, err } from './result.js';
+/**
+ * Validate that a raw parsed object conforms to the LayerConfig schema.
+ */
+export function validateConfigSchema(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        return err({ type: 'config-validation-error', message: 'Config must be a JSON object' });
+    }
+    const obj = raw;
+    // Validate 'layers' field
+    if (typeof obj.layers !== 'object' || obj.layers === null) {
+        return err({
+            type: 'config-validation-error',
+            message: 'Config must have a "layers" object',
+        });
+    }
+    // Validate each layer definition
+    const layers = obj.layers;
+    const errors = [];
+    for (const [layerName, layerDef] of Object.entries(layers)) {
+        const result = validateLayerDefinition(layerName, layerDef);
+        if (!result.success) {
+            errors.push(result.error.message);
+        }
+    }
+    if (errors.length > 0) {
+        return err({
+            type: 'config-validation-error',
+            message: 'Invalid layer definitions',
+            details: errors,
+        });
+    }
+    // Validate optional 'enforcement' field
+    if (obj.enforcement !== undefined) {
+        if (typeof obj.enforcement !== 'object' || obj.enforcement === null) {
+            return err({
+                type: 'config-validation-error',
+                message: '"enforcement" field must be an object if defined',
+            });
+        }
+        const enforcement = obj.enforcement;
+        if (enforcement.mode !== undefined &&
+            (typeof enforcement.mode !== 'string' ||
+                !['error', 'warn', 'off'].includes(enforcement.mode))) {
+            return err({
+                type: 'config-validation-error',
+                message: `Invalid enforcement mode: "${enforcement.mode}". Must be "error", "warn", or "off"`,
+            });
+        }
+    }
+    // Validate optional 'workspaces'
+    if (obj.workspaces !== undefined) {
+        if (typeof obj.workspaces !== 'object' || obj.workspaces === null) {
+            return err({
+                type: 'config-validation-error',
+                message: '"workspaces" must be an object',
+            });
+        }
+        const workspaces = obj.workspaces;
+        if (workspaces.patterns !== undefined &&
+            (!Array.isArray(workspaces.patterns) ||
+                !workspaces.patterns.every((p) => typeof p === 'string'))) {
+            return err({
+                type: 'config-validation-error',
+                message: '"workspaces.patterns" must be an array of strings',
+            });
+        }
+    }
+    return ok({
+        layers: obj.layers,
+        enforcement: obj.enforcement,
+        workspaces: obj.workspaces,
+    });
+}
+/**
+ * Validate a single layer definition.
+ */
+export function validateLayerDefinition(name, raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return err({
+            type: 'config-validation-error',
+            message: `Layer "${name}" must be an object`,
+        });
+    }
+    const def = raw;
+    if (!Array.isArray(def.allowedDependencies)) {
+        return err({
+            type: 'config-validation-error',
+            message: `Layer "${name}" must have an "allowedDependencies" array`,
+        });
+    }
+    if (!def.allowedDependencies.every((d) => typeof d === 'string')) {
+        return err({
+            type: 'config-validation-error',
+            message: `Layer "${name}" allowedDependencies must contain only strings`,
+        });
+    }
+    return ok({
+        description: typeof def.description === 'string' ? def.description : undefined,
+        allowedDependencies: def.allowedDependencies,
+    });
+}

package/lib/core/errors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Union of all possible errors in the enforce-layers system.
+ */
+export type LayerError = ConfigError | DiscoveryError;
+/**
+ * Errors that can occur during configuration loading and validation.
+ */
+export type ConfigError = {
+    type: 'config-not-found';
+    message: string;
+    path: string;
+} | {
+    type: 'config-read-error';
+    message: string;
+    path: string;
+    cause?: unknown;
+} | {
+    type: 'config-parse-error';
+    message: string;
+    path: string;
+    cause?: unknown;
+} | {
+    type: 'config-validation-error';
+    message: string;
+    details?: string[];
+};
+/**
+ * Errors that can occur during package discovery.
+ */
+export type DiscoveryError = {
+    type: 'glob-failed';
+    message: string;
+    pattern: string;
+    cause?: unknown;
+} | {
+    type: 'package-parse-error';
+    message: string;
+    path: string;
+    cause?: unknown;
+};
+/**
+ * Format any LayerError into a human-readable string.
+ */
+export declare function formatLayerError(error: LayerError): string;

package/lib/core/errors.js

@@ -0,0 +1,25 @@
+/**
+ * Format any LayerError into a human-readable string.
+ */
+export function formatLayerError(error) {
+    switch (error.type) {
+        case 'config-not-found':
+            return `Config file not found: ${error.path}`;
+        case 'config-read-error':
+            return `Failed to read config file (${error.path}): ${error.message}`;
+        case 'config-parse-error':
+            return `Invalid JSON in config file (${error.path}): ${error.message}`;
+        case 'config-validation-error':
+            return error.details
+                ? `Config validation failed:\n${error.details.map(d => `  - ${d}`).join('\n')}`
+                : `Config validation failed: ${error.message}`;
+        case 'glob-failed':
+            return `Glob pattern failed (${error.pattern}): ${error.message}`;
+        case 'package-parse-error':
+            return `Failed to parse package at ${error.path}: ${error.message}`;
+        default: {
+            const _exhaustive = error;
+            return `Unknown error: ${_exhaustive.message}`;
+        }
+    }
+}

package/lib/core/formatters/console-formatter.d.ts

@@ -0,0 +1,3 @@
+import type { ValidationReport } from '../report-builder.js';
+import type { EnforcementConfig } from '../../types/types.js';
+export declare function formatConsole(report: ValidationReport, mode: EnforcementConfig['mode']): string;

package/lib/core/formatters/console-formatter.js

@@ -0,0 +1,34 @@
+const TYPE_LABELS = {
+    'missing-layer': '🏷️  Missing Layer',
+    'unknown-layer': '❓ Unknown Layer',
+    'invalid-dependency': '🚫 Invalid Dependency',
+};
+export function formatConsole(report, mode) {
+    const lines = [];
+    const durationStr = formatDuration(report.duration);
+    if (report.violations.length === 0) {
+        lines.push('✅ All packages comply with layer rules!');
+        lines.push(`\n⏱️  Completed in ${durationStr}`);
+        return lines.join('\n');
+    }
+    lines.push(`❌ Found ${report.violationCount} layer violations:\n`);
+    for (const [type, violations] of Object.entries(report.violationsByType)) {
+        if (!violations || violations.length === 0) {
+            continue;
+        }
+        const label = TYPE_LABELS[type] ?? type;
+        lines.push(`  ${label} (${violations.length}):`);
+        for (const v of violations) {
+            lines.push(`    • ${v.message}`);
+        }
+        lines.push('');
+    }
+    lines.push(`⏱️  Completed in ${durationStr}`);
+    if (mode === 'warn') {
+        lines.push('\n⚠️  Enforcement mode: warn - not failing build');
+    }
+    return lines.join('\n');
+}
+function formatDuration(ms) {
+    return ms < 1000 ? `${ms.toFixed(0)}ms` : `${(ms / 1000).toFixed(2)}s`;
+}

package/lib/core/formatters/json-formatter.d.ts

@@ -0,0 +1,5 @@
+import type { ValidationReport } from '../report-builder.js';
+/**
+ * Format a validation report as a JSON string.
+ */
+export declare function formatJson(report: ValidationReport): string;

package/lib/core/formatters/json-formatter.js

@@ -0,0 +1,11 @@
+/**
+ * Format a validation report as a JSON string.
+ */
+export function formatJson(report) {
+    return JSON.stringify({
+        violations: report.violations,
+        totalPackages: report.totalPackages,
+        violationCount: report.violationCount,
+        duration: report.duration,
+    }, null, 2);
+}

package/lib/core/package-parser.d.ts

@@ -0,0 +1,11 @@
+import type { Package } from '../types/types.js';
+import type { DiscoveryError } from './errors.js';
+import type { Result } from './result.js';
+/**
+ * Parse a raw package.json object into a Package.
+ */
+export declare function parsePackageJson(content: unknown, relativePath: string): Result<Package, DiscoveryError>;
+/**
+ * Extract workspace: protocol dependencies from deps, devDeps, and peerDeps.
+ */
+export declare function extractWorkspaceDependencies(dependencies?: Record<string, string>, devDependencies?: Record<string, string>, peerDependencies?: Record<string, string>): string[];

package/lib/core/package-parser.js

@@ -0,0 +1,37 @@
+import { ok, err } from './result.js';
+/**
+ * Parse a raw package.json object into a Package.
+ */
+export function parsePackageJson(content, relativePath) {
+    if (typeof content !== 'object' || content === null) {
+        return err({
+            type: 'package-parse-error',
+            message: `Invalid package.json at "${relativePath}": must be a JSON object`,
+            path: relativePath,
+        });
+    }
+    const pkg = content;
+    // Validate required fields
+    if (typeof pkg.name !== 'string' || pkg.name.trim() === '') {
+        return err({
+            type: 'package-parse-error',
+            message: `Invalid package.json at "${relativePath}": missing or invalid "name" field`,
+            path: relativePath,
+        });
+    }
+    return ok({
+        name: pkg.name,
+        layer: typeof pkg.layer === 'string' ? pkg.layer : undefined,
+        dependencies: extractWorkspaceDependencies(pkg.dependencies, pkg.devDependencies, pkg.peerDependencies),
+        path: relativePath,
+    });
+}
+/**
+ * Extract workspace: protocol dependencies from deps, devDeps, and peerDeps.
+ */
+export function extractWorkspaceDependencies(dependencies, devDependencies, peerDependencies) {
+    const allDeps = { ...dependencies, ...devDependencies, ...peerDependencies };
+    return Object.entries(allDeps)
+        .filter(([_, version]) => typeof version === 'string' && version.startsWith('workspace:'))
+        .map(([name, _]) => name);
+}

package/lib/core/report-builder.d.ts

@@ -0,0 +1,18 @@
+import type { Violation, ViolationType } from '../types/types.js';
+/**
+ * Structured report produced after validation.
+ */
+export interface ValidationReport {
+    violations: Violation[];
+    totalPackages: number;
+    violationsByType: Partial<Record<ViolationType, Violation[]>>;
+    violationCount: number;
+    duration: number;
+}
+/**
+ * Build a structured report from violations and metadata.
+ */
+export declare function buildReport(violations: Violation[], metadata: {
+    totalPackages: number;
+    duration: number;
+}): ValidationReport;

package/lib/core/report-builder.js

@@ -0,0 +1,17 @@
+/**
+ * Build a structured report from violations and metadata.
+ */
+export function buildReport(violations, metadata) {
+    const violationsByType = {};
+    // Group violations by type for easier reporting
+    for (const violation of violations) {
+        (violationsByType[violation.type] ??= []).push(violation);
+    }
+    return {
+        violations,
+        totalPackages: metadata.totalPackages,
+        violationsByType,
+        violationCount: violations.length,
+        duration: metadata.duration,
+    };
+}

package/lib/core/result.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A discriminated union representing either a successful value or an error.
+ * Used throughout the library to make error handling explicit and type-safe.
+ */
+export type Result<T, E> = {
+    readonly success: true;
+    readonly value: T;
+} | {
+    readonly success: false;
+    readonly error: E;
+};
+/**
+ * Create a successful Result containing the given value.
+ */
+export declare function ok<T>(value: T): Result<T, never>;
+/**
+ * Create a failed Result containing the given error.
+ */
+export declare function err<E>(error: E): Result<never, E>;
+/**
+ * Type guard for successful Results.
+ */
+export declare function isOk<T, E>(result: Result<T, E>): result is {
+    success: true;
+    value: T;
+};
+/**
+ * Type guard for failed Results.
+ */
+export declare function isErr<T, E>(result: Result<T, E>): result is {
+    success: false;
+    error: E;
+};

package/lib/core/result.js

@@ -0,0 +1,24 @@
+/**
+ * Create a successful Result containing the given value.
+ */
+export function ok(value) {
+    return { success: true, value };
+}
+/**
+ * Create a failed Result containing the given error.
+ */
+export function err(error) {
+    return { success: false, error };
+}
+/**
+ * Type guard for successful Results.
+ */
+export function isOk(result) {
+    return result.success;
+}
+/**
+ * Type guard for failed Results.
+ */
+export function isErr(result) {
+    return !result.success;
+}

package/lib/core/rules.d.ts

@@ -0,0 +1,14 @@
+import type { Package, LayerMap } from '../types/types.js';
+/**
+ * Check whether a package has the required "layer" field.
+ */
+export declare function hasRequiredLayer(pkg: Package): boolean;
+/**
+ * Check whether a layer name is defined in the config.
+ */
+export declare function isKnownLayer(layerName: string, layers: LayerMap): boolean;
+/**
+ * Check whether a dependency from one layer to another is permitted.
+ * Wildcard '*' in allowedDependencies permits any target layer.
+ */
+export declare function isDependencyAllowed(fromLayer: string, toLayer: string, allowedDependencies: string[]): boolean;

package/lib/core/rules.js

@@ -0,0 +1,19 @@
+/**
+ * Check whether a package has the required "layer" field.
+ */
+export function hasRequiredLayer(pkg) {
+    return pkg.layer !== undefined && pkg.layer !== '';
+}
+/**
+ * Check whether a layer name is defined in the config.
+ */
+export function isKnownLayer(layerName, layers) {
+    return layerName in layers;
+}
+/**
+ * Check whether a dependency from one layer to another is permitted.
+ * Wildcard '*' in allowedDependencies permits any target layer.
+ */
+export function isDependencyAllowed(fromLayer, toLayer, allowedDependencies) {
+    return allowedDependencies.includes('*') || allowedDependencies.includes(toLayer);
+}

package/lib/core/validation.d.ts

@@ -0,0 +1,5 @@
+import type { Package, ResolvedConfig, Violation } from '../types/types.js';
+/**
+ * Validate all packages against layer configuration.
+ */
+export declare function validatePackages(packages: Package[], config: ResolvedConfig): Violation[];