@domainlang/cli 0.5.2 → 0.7.0

package/src/services/governance-validator.ts

@@ -0,0 +1,226 @@
+/**
+ * Governance and Compliance Validation Service (CLI-only)
+ * 
+ * Enforces organizational policies and best practices:
+ * - Allowed/blocked dependency sources
+ * - Version policy enforcement (no pre-release in production)
+ * - Team ownership validation
+ * - License compliance
+ * - Audit trail generation
+ * 
+ * Governance policies are defined in the `governance` section of model.yaml:
+ * 
+ * ```yaml
+ * governance:
+ *   allowedSources:
+ *     - github.com/acme
+ *   requireStableVersions: true
+ *   requireTeamOwnership: true
+ * ```
+ */
+
+import type { LockFile, GovernancePolicy, GovernanceMetadata, GovernanceViolation } from './types.js';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import YAML from 'yaml';
+import { isPreRelease } from './semver.js';
+
+/** Locked dependency entry from lock file */
+interface LockedDependency {
+    resolved: string;
+    ref: string;
+    commit: string;
+}
+
+/**
+ * Validates dependencies against organizational governance policies.
+ */
+export class GovernanceValidator {
+    constructor(private readonly policy: GovernancePolicy) {}
+
+    /**
+     * Validates a lock file against governance policies.
+     */
+    async validate(lockFile: LockFile, workspaceRoot: string): Promise<GovernanceViolation[]> {
+        const violations: GovernanceViolation[] = [];
+
+        // Validate each dependency
+        for (const [packageKey, locked] of Object.entries(lockFile.dependencies)) {
+            violations.push(
+                ...this.validateAllowedSources(packageKey, locked),
+                ...this.validateBlockedPackages(packageKey),
+                ...this.validateVersionStability(packageKey, locked)
+            );
+        }
+
+        // Validate workspace metadata
+        if (this.policy.requireTeamOwnership) {
+            const metadata = await this.loadGovernanceMetadata(workspaceRoot);
+            if (!metadata.team || !metadata.contact) {
+                violations.push({
+                    type: 'missing-metadata',
+                    packageKey: 'workspace',
+                    message: 'Missing required team ownership metadata in model.yaml',
+                    severity: 'warning',
+                });
+            }
+        }
+
+        return violations;
+    }
+
+    /**
+     * Checks if package source is allowed by policy.
+     */
+    private validateAllowedSources(
+        packageKey: string,
+        locked: LockedDependency
+    ): GovernanceViolation[] {
+        if (!this.policy.allowedSources || this.policy.allowedSources.length === 0) {
+            return [];
+        }
+
+        const isAllowed = this.policy.allowedSources.some(
+            pattern => locked.resolved.includes(pattern) || packageKey.startsWith(pattern)
+        );
+
+        if (!isAllowed) {
+            return [{
+                type: 'blocked-source',
+                packageKey,
+                message: `Package from unauthorized source: ${locked.resolved}`,
+                severity: 'error',
+            }];
+        }
+
+        return [];
+    }
+
+    /**
+     * Checks if package is explicitly blocked by policy.
+     */
+    private validateBlockedPackages(packageKey: string): GovernanceViolation[] {
+        if (!this.policy.blockedPackages) {
+            return [];
+        }
+
+        const isBlocked = this.policy.blockedPackages.some(
+            pattern => packageKey.includes(pattern)
+        );
+
+        if (isBlocked) {
+            return [{
+                type: 'blocked-source',
+                packageKey,
+                message: `Package is blocked by governance policy`,
+                severity: 'error',
+            }];
+        }
+
+        return [];
+    }
+
+    /**
+     * Checks if package version meets stability requirements.
+     */
+    private validateVersionStability(
+        packageKey: string,
+        locked: Pick<LockedDependency, 'ref'>
+    ): GovernanceViolation[] {
+        if (!this.policy.requireStableVersions) {
+            return [];
+        }
+
+        if (isPreRelease(locked.ref)) {
+            return [{
+                type: 'unstable-version',
+                packageKey,
+                message: `Pre-release ref not allowed: ${locked.ref}`,
+                severity: 'error',
+            }];
+        }
+
+        return [];
+    }
+
+    /**
+     * Loads governance metadata from model.yaml.
+     */
+    async loadGovernanceMetadata(workspaceRoot: string): Promise<GovernanceMetadata> {
+        const manifestPath = path.join(workspaceRoot, 'model.yaml');
+
+        try {
+            const content = await fs.readFile(manifestPath, 'utf-8');
+            const manifest = YAML.parse(content) as {
+                metadata?: GovernanceMetadata;
+            };
+
+            return manifest.metadata ?? {};
+        } catch {
+            return {};
+        }
+    }
+
+    /**
+     * Generates an audit report for compliance tracking.
+     */
+    async generateAuditReport(lockFile: LockFile, workspaceRoot: string): Promise<string> {
+        const metadata = await this.loadGovernanceMetadata(workspaceRoot);
+        const violations = await this.validate(lockFile, workspaceRoot);
+
+        // Build header section
+        const headerLines = [
+            '=== Dependency Audit Report ===',
+            '',
+            `Workspace: ${workspaceRoot}`,
+            `Team: ${metadata.team ?? 'N/A'}`,
+            `Contact: ${metadata.contact ?? 'N/A'}`,
+            `Domain: ${metadata.domain ?? 'N/A'}`,
+            '',
+            'Dependencies:',
+        ];
+
+        // Build dependencies section
+        const depLines: string[] = [];
+        for (const [packageKey, locked] of Object.entries(lockFile.dependencies)) {
+            depLines.push(
+                `  - ${packageKey}@${locked.ref}`,
+                `    Source: ${locked.resolved}`,
+                `    Commit: ${locked.commit}`
+            );
+        }
+
+        // Build violations section
+        const violationLines = violations.length > 0
+            ? [
+                '',
+                'Violations:',
+                ...violations.map(v => 
+                    `  [${v.severity.toUpperCase()}] ${v.packageKey}: ${v.message}`
+                )
+            ]
+            : ['', '\u2713 No policy violations detected'];
+
+        return [...headerLines, ...depLines, ...violationLines].join('\n');
+    }
+}
+
+/**
+ * Loads governance policy from model.yaml governance section.
+ */
+export async function loadGovernancePolicy(workspaceRoot: string): Promise<GovernancePolicy> {
+    const manifestPath = path.join(workspaceRoot, 'model.yaml');
+
+    try {
+        const content = await fs.readFile(manifestPath, 'utf-8');
+        const manifest = YAML.parse(content) as {
+            governance?: GovernancePolicy;
+        };
+        
+        // Return governance section or empty policy if not defined
+        return manifest.governance ?? {};
+    } catch {
+        // No manifest or parse error = permissive defaults
+        return {};
+    }
+}

package/src/services/index.ts

@@ -0,0 +1,13 @@
+/**
+ * CLI Services Index
+ * 
+ * Exports all CLI-only services for package management.
+ * These services contain network operations and should never be used in LSP.
+ */
+
+export * from './types.js';
+export * from './semver.js';
+export * from './git-url-resolver.js';
+export * from './dependency-resolver.js';
+export * from './dependency-analyzer.js';
+export * from './governance-validator.js';

package/src/services/semver.ts

@@ -0,0 +1,213 @@
+/**
+ * Semantic Versioning Utilities (CLI-only)
+ * 
+ * Centralized SemVer parsing, comparison, and validation for the dependency system.
+ * All version-related logic should use these utilities to ensure consistency.
+ * 
+ * Supported formats:
+ * - "1.0.0" or "v1.0.0" (tags)
+ * - "1.0.0-alpha.1" (pre-release)
+ * - "main", "develop" (branches)
+ * - "abc123def" (commit SHAs, 7-40 hex chars)
+ */
+
+import type { SemVer, RefType, ParsedRef } from './types.js';
+
+// ============================================================================
+// Parsing
+// ============================================================================
+
+/**
+ * Parses a version string into SemVer components.
+ * Returns undefined if not a valid SemVer.
+ * 
+ * @example
+ * parseSemVer("v1.2.3")       // { major: 1, minor: 2, patch: 3, original: "v1.2.3" }
+ * parseSemVer("1.0.0-alpha")  // { major: 1, minor: 0, patch: 0, prerelease: "alpha", ... }
+ * parseSemVer("main")         // undefined (not SemVer)
+ */
+export function parseSemVer(version: string): SemVer | undefined {
+    // Strip leading 'v' if present
+    const normalized = version.startsWith('v') ? version.slice(1) : version;
+    
+    // Match semver pattern: major.minor.patch[-prerelease]
+    const match = normalized.match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+    if (!match) return undefined;
+    
+    return {
+        major: parseInt(match[1], 10),
+        minor: parseInt(match[2], 10),
+        patch: parseInt(match[3], 10),
+        preRelease: match[4],
+        original: version,
+    };
+}
+
+/**
+ * Detects the type of a git ref based on its format.
+ * 
+ * @example
+ * detectRefType("v1.0.0")    // 'tag'
+ * detectRefType("1.2.3")     // 'tag'
+ * detectRefType("main")      // 'branch'
+ * detectRefType("abc123def") // 'commit'
+ */
+export function detectRefType(ref: string): RefType {
+    // Commit SHA: 7-40 hex characters
+    if (/^[0-9a-f]{7,40}$/i.test(ref)) {
+        return 'commit';
+    }
+    // Tags typically start with 'v' followed by semver
+    if (/^v?\d+\.\d+\.\d+/.test(ref)) {
+        return 'tag';
+    }
+    // Everything else is treated as a branch
+    return 'branch';
+}
+
+/**
+ * Parses a ref string into a structured ParsedRef with type and optional SemVer.
+ */
+export function parseRef(ref: string): ParsedRef {
+    const type = detectRefType(ref);
+    const semver = type === 'tag' ? parseSemVer(ref) : undefined;
+    
+    return { original: ref, type, semver };
+}
+
+// ============================================================================
+// Comparison
+// ============================================================================
+
+/**
+ * Compares two SemVer versions.
+ * Returns: negative if a < b, positive if a > b, zero if equal.
+ * 
+ * @example
+ * compareSemVer(parse("1.0.0"), parse("2.0.0")) // negative (a < b)
+ * compareSemVer(parse("1.5.0"), parse("1.2.0")) // positive (a > b)
+ * compareSemVer(parse("1.0.0-alpha"), parse("1.0.0")) // negative (prerelease < release)
+ */
+export function compareSemVer(a: SemVer, b: SemVer): number {
+    if (a.major !== b.major) return a.major - b.major;
+    if (a.minor !== b.minor) return a.minor - b.minor;
+    if (a.patch !== b.patch) return a.patch - b.patch;
+    
+    // Pre-release versions are lower than release versions
+    if (a.preRelease && !b.preRelease) return -1;
+    if (!a.preRelease && b.preRelease) return 1;
+    if (a.preRelease && b.preRelease) {
+        return a.preRelease.localeCompare(b.preRelease);
+    }
+    
+    return 0;
+}
+
+/**
+ * Picks the latest from a list of SemVer refs.
+ * Returns the ref string (with original 'v' prefix if present).
+ * 
+ * @example
+ * pickLatestSemVer(["v1.0.0", "v1.5.0", "v1.2.0"]) // "v1.5.0"
+ */
+export function pickLatestSemVer(refs: string[]): string | undefined {
+    const parsed = refs
+        .map(ref => ({ ref, semver: parseSemVer(ref) }))
+        .filter((item): item is { ref: string; semver: SemVer } => item.semver !== undefined);
+    
+    if (parsed.length === 0) return undefined;
+    
+    parsed.sort((a, b) => compareSemVer(b.semver, a.semver)); // Descending
+    return parsed[0].ref;
+}
+
+/**
+ * Sorts version strings in descending order (newest first).
+ * Non-SemVer refs are sorted lexicographically at the end.
+ * 
+ * @example
+ * sortVersionsDescending(["v1.0.0", "v2.0.0", "v1.5.0"]) // ["v2.0.0", "v1.5.0", "v1.0.0"]
+ */
+export function sortVersionsDescending(versions: string[]): string[] {
+    return [...versions].sort((a, b) => {
+        const semverA = parseSemVer(a);
+        const semverB = parseSemVer(b);
+        
+        // Both are SemVer - compare semantically
+        if (semverA && semverB) {
+            return compareSemVer(semverB, semverA); // Descending
+        }
+        
+        // SemVer comes before non-SemVer
+        if (semverA && !semverB) return -1;
+        if (!semverA && semverB) return 1;
+        
+        // Both non-SemVer - lexicographic
+        return b.localeCompare(a);
+    });
+}
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+/**
+ * Checks if a version/ref is a pre-release.
+ * 
+ * Pre-release identifiers: alpha, beta, rc, pre, dev, snapshot
+ * 
+ * @example
+ * isPreRelease("v1.0.0")       // false
+ * isPreRelease("v1.0.0-alpha") // true
+ * isPreRelease("v1.0.0-rc.1")  // true
+ */
+export function isPreRelease(ref: string): boolean {
+    const semver = parseSemVer(ref);
+    if (semver?.preRelease) {
+        return true;
+    }
+    
+    // Also check for common pre-release patterns without proper SemVer
+    const clean = ref.replace(/^v/, '');
+    return /-(alpha|beta|rc|pre|dev|snapshot)/i.test(clean);
+}
+
+/**
+ * Checks if two SemVer versions are compatible (same major version).
+ * 
+ * @example
+ * areSameMajor(parse("1.0.0"), parse("1.5.0")) // true
+ * areSameMajor(parse("1.0.0"), parse("2.0.0")) // false
+ */
+export function areSameMajor(a: SemVer, b: SemVer): boolean {
+    return a.major === b.major;
+}
+
+/**
+ * Gets the major version number from a ref string.
+ * Returns undefined if not a valid SemVer.
+ */
+export function getMajorVersion(ref: string): number | undefined {
+    return parseSemVer(ref)?.major;
+}
+
+// ============================================================================
+// Filtering
+// ============================================================================
+
+/**
+ * Filters refs to only stable versions (excludes pre-releases).
+ * 
+ * @example
+ * filterStableVersions(["v1.0.0", "v1.1.0-alpha", "v1.2.0"]) // ["v1.0.0", "v1.2.0"]
+ */
+export function filterStableVersions(refs: string[]): string[] {
+    return refs.filter(ref => !isPreRelease(ref));
+}
+
+/**
+ * Filters refs to only SemVer tags (excludes branches and commits).
+ */
+export function filterSemVerTags(refs: string[]): string[] {
+    return refs.filter(ref => detectRefType(ref) === 'tag' && parseSemVer(ref) !== undefined);
+}

package/src/services/types.ts

@@ -0,0 +1,81 @@
+/**
+ * Types for CLI-only package management services.
+ * 
+ * These types support git-based dependency resolution and governance
+ * that only runs in the CLI context (never in LSP).
+ */
+
+import type { RefType } from '@domainlang/language';
+
+// Re-export types that are shared with language package
+export type {
+    LockFile,
+    LockedDependency,
+    ModelManifest,
+    DependencySpec,
+    ExtendedDependencySpec,
+    PathAliases,
+    GovernancePolicy,
+    GovernanceMetadata,
+    GovernanceViolation,
+    DependencyTreeNode,
+    ReverseDependency,
+    VersionPolicy,
+    SemVer,
+    RefType,
+    ParsedRef,
+} from '@domainlang/language';
+
+/**
+ * Parsed git import URL information.
+ */
+export interface GitImportInfo {
+    /** Original import string */
+    original: string;
+    /** Detected platform (github, gitlab, bitbucket, generic) */
+    platform: 'github' | 'gitlab' | 'bitbucket' | 'generic';
+    /** Repository owner/organization */
+    owner: string;
+    /** Repository name */
+    repo: string;
+    /** Version/tag/branch/commit */
+    version: string;
+    /** Full repository URL without version */
+    repoUrl: string;
+    /** Entry point file (default: index.dlang) */
+    entryPoint: string;
+}
+
+/**
+ * Package configuration during dependency resolution.
+ */
+export interface ResolvingPackage {
+    name?: string;
+    version?: string;
+    entry?: string;
+    dependencies?: Record<string, string>;
+    overrides?: Record<string, string>;
+}
+
+/**
+ * Dependency graph for resolution.
+ */
+export interface DependencyGraph {
+    nodes: Record<string, DependencyGraphNode>;
+    root: string;
+}
+
+/**
+ * Node in the dependency graph.
+ */
+export interface DependencyGraphNode {
+    packageKey: string;
+    refConstraint: string;
+    constraints?: Set<string>;
+    repoUrl?: string;
+    dependencies: Record<string, string>;
+    dependents: string[];
+    resolvedRef?: string;
+    refType?: RefType;
+    commitHash?: string;
+}