@domainlang/language 0.1.20

package/src/services/semver.ts

@@ -0,0 +1,213 @@
+/**
+ * Semantic Versioning Utilities
+ * 
+ * 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,415 @@
+/**
+ * Centralized Type Definitions for DomainLang Services
+ * 
+ * Type design principles:
+ * - **Atomic**: Each type represents a single, well-defined concept
+ * - **Non-overlapping**: Types don't duplicate fields unnecessarily
+ * - **Rich**: Types use adjacent types for composition rather than primitives
+ * - **Discriminated**: Union types use discriminants for type narrowing
+ * 
+ * Type hierarchy:
+ * ```
+ * Core Building Blocks
+ *   ├── RefType (discriminant for git references)
+ *   └── SemVer (semantic version components)
+ * 
+ * Package Identity
+ *   └── PackageIdentity (name, version, entry)
+ * 
+ * Dependencies
+ *   ├── DependencySpec (how deps are specified)
+ *   │   ├── ShortDependencySpec (string ref only)
+ *   │   └── ExtendedDependencySpec (full options)
+ *   └── ResolvedDependency (locked/pinned state)
+ * 
+ * Manifest & Lock
+ *   ├── ModelManifest (model.yaml schema)
+ *   └── LockFile (model.lock schema)
+ * 
+ * Resolution Graph
+ *   ├── DependencyNode (graph node during resolution)
+ *   └── DependencyGraph (complete resolution graph)
+ * 
+ * Analysis & Governance
+ *   ├── GovernancePolicy (policy configuration)
+ *   └── GovernanceViolation (validation result)
+ * ```
+ * 
+ * @module services/types
+ */
+
+// ============================================================================
+// Core Building Blocks
+// ============================================================================
+
+/**
+ * Type of git reference for version pinning.
+ * 
+ * Used as discriminant in ref-related types:
+ * - **tag**: SemVer version tag (v1.0.0, 2.3.4)
+ * - **branch**: Branch name (main, develop)
+ * - **commit**: Full commit SHA (40 hex chars)
+ */
+export type RefType = 'tag' | 'branch' | 'commit';
+
+/**
+ * Parsed semantic version following SemVer 2.0.0.
+ * 
+ * @example
+ * ```typescript
+ * const v: SemVer = {
+ *   major: 1, minor: 2, patch: 3,
+ *   preRelease: 'beta.1',
+ *   original: 'v1.2.3-beta.1'
+ * };
+ * ```
+ */
+export interface SemVer {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    /** Pre-release identifier (e.g., "alpha", "beta.1", "rc.2") */
+    readonly preRelease?: string;
+    /** Build metadata - ignored in version comparison */
+    readonly buildMetadata?: string;
+    /** Original string representation */
+    readonly original: string;
+}
+
+/**
+ * Result of parsing a git ref string.
+ */
+export interface ParsedRef {
+    readonly type: RefType;
+    /** Present only for valid SemVer tags */
+    readonly semver?: SemVer;
+    readonly original: string;
+}
+
+// ============================================================================
+// Package Identity
+// ============================================================================
+
+/**
+ * Core package identity and metadata.
+ * 
+ * Used in model.yaml `model:` section and internally during resolution.
+ */
+export interface PackageIdentity {
+    /** Package name in owner/repo format */
+    readonly name?: string;
+    /** SemVer version string */
+    readonly version?: string;
+    /** Entry point file (default: index.dlang) */
+    readonly entry?: string;
+}
+
+// ============================================================================
+// Dependency Specification Types
+// ============================================================================
+
+/**
+ * Extended dependency specification with full options.
+ * 
+ * Either `source` OR `path` must be provided (mutually exclusive):
+ * - `source`: Remote git coordinates (owner/repo)
+ * - `path`: Local filesystem path for monorepo deps
+ */
+export interface ExtendedDependencySpec {
+    /** Git coordinates (owner/repo) - mutually exclusive with path */
+    readonly source?: string;
+    /** Git ref (tag, branch, or commit SHA) */
+    readonly ref?: string;
+    /** Local path - mutually exclusive with source */
+    readonly path?: string;
+    /** SHA-256 integrity hash for verification */
+    readonly integrity?: string;
+    /** Human-readable description */
+    readonly description?: string;
+}
+
+/**
+ * Dependency specification in model.yaml.
+ * 
+ * Can be either:
+ * - **string**: Short form (just the ref, key is owner/repo)
+ * - **ExtendedDependencySpec**: Full form with options
+ * 
+ * @example
+ * ```yaml
+ * dependencies:
+ *   acme/core: "v1.0.0"              # Short form
+ *   acme/utils:                       # Extended form
+ *     source: acme/utils
+ *     ref: main
+ *     integrity: sha256-abc123
+ * ```
+ */
+export type DependencySpec = string | ExtendedDependencySpec;
+
+/**
+ * Type guard for extended dependency spec.
+ */
+export function isExtendedDependencySpec(dep: DependencySpec): dep is ExtendedDependencySpec {
+    return typeof dep === 'object' && dep !== null;
+}
+
+// ============================================================================
+// Resolved/Locked Dependency Types
+// ============================================================================
+
+/**
+ * A fully resolved and locked dependency.
+ * 
+ * Represents a dependency after resolution with all fields pinned
+ * to exact values for reproducible builds.
+ */
+export interface LockedDependency {
+    /** Original ref from manifest */
+    readonly ref: string;
+    /** Detected ref type */
+    readonly refType: RefType;
+    /** Full git URL used for fetching */
+    readonly resolved: string;
+    /** Exact commit hash (40-char SHA) */
+    readonly commit: string;
+    /** Optional integrity hash */
+    readonly integrity?: string;
+}
+
+// ============================================================================
+// Manifest Types (model.yaml)
+// ============================================================================
+
+/**
+ * Path aliases for @ imports.
+ * 
+ * @example
+ * ```yaml
+ * paths:
+ *   "@/": "./src/"
+ *   "@shared/": "./libs/shared/"
+ * ```
+ */
+export type PathAliases = Readonly<Record<string, string>>;
+
+/**
+ * Governance policy configuration.
+ */
+export interface GovernancePolicy {
+    /** Allowed git domains (e.g., ['github.com/acme']) */
+    readonly allowedSources?: readonly string[];
+    /** Blocked packages or patterns */
+    readonly blockedPackages?: readonly string[];
+    /** Require stable versions only (no pre-release) */
+    readonly requireStableVersions?: boolean;
+    /** Require team ownership metadata */
+    readonly requireTeamOwnership?: boolean;
+    /** Allowed licenses */
+    readonly allowedLicenses?: readonly string[];
+}
+
+/**
+ * Package manifest (model.yaml) schema.
+ * 
+ * This is the user-facing YAML file structure.
+ */
+export interface ModelManifest {
+    /** Package identity and metadata */
+    readonly model?: PackageIdentity;
+    /** Path aliases for @ imports */
+    readonly paths?: PathAliases;
+    /** Dependencies keyed by alias or owner/repo */
+    readonly dependencies?: Readonly<Record<string, DependencySpec>>;
+    /** Ref overrides for conflict resolution */
+    readonly overrides?: Readonly<Record<string, string>>;
+    /** Governance policies */
+    readonly governance?: GovernancePolicy;
+}
+
+// ============================================================================
+// Lock File Types (model.lock)
+// ============================================================================
+
+/**
+ * Lock file schema (model.lock).
+ * 
+ * Pins exact commits for reproducible builds.
+ */
+export interface LockFile {
+    /** Lock file format version */
+    readonly version: string;
+    /** All locked dependencies keyed by package name */
+    readonly dependencies: Readonly<Record<string, LockedDependency>>;
+}
+
+// ============================================================================
+// Dependency Resolution Types (internal)
+// ============================================================================
+
+/**
+ * Mutable package metadata during resolution.
+ * 
+ * Unlike PackageIdentity (readonly user-facing), this is mutable
+ * because the resolver builds it incrementally during YAML parsing.
+ */
+export interface ResolvingPackage {
+    name?: string;
+    version?: string;
+    entry?: string;
+    exports?: Record<string, string>;
+    /** Dependencies as name → ref constraint */
+    dependencies?: Record<string, string>;
+    /** Ref overrides */
+    overrides?: Record<string, string>;
+}
+
+/**
+ * Node in the dependency graph during resolution.
+ */
+export interface DependencyNode {
+    /** Package identifier (owner/repo) */
+    readonly packageKey: string;
+    /** Primary ref constraint from first encounter */
+    refConstraint: string;
+    /** All observed constraints from different parents */
+    constraints?: Set<string>;
+    /** Resolved ref after conflict resolution */
+    resolvedRef?: string;
+    /** Detected ref type */
+    refType?: RefType;
+    /** Resolved commit hash */
+    commitHash?: string;
+    /** Full git repository URL */
+    repoUrl?: string;
+    /** Direct dependencies of this package */
+    dependencies: Record<string, string>;
+    /** Parent packages that depend on this one */
+    dependents: string[];
+}
+
+/**
+ * Complete dependency graph for resolution.
+ */
+export interface DependencyGraph {
+    /** All discovered packages */
+    readonly nodes: Record<string, DependencyNode>;
+    /** Root package name */
+    readonly root: string;
+}
+
+// ============================================================================
+// Git Import Types
+// ============================================================================
+
+/** Supported git platforms */
+export type GitPlatform = 'github' | 'gitlab' | 'bitbucket' | 'generic';
+
+/**
+ * Parsed git import with repository information.
+ */
+export interface GitImportInfo {
+    /** Original import string */
+    readonly original: string;
+    /** Git platform */
+    readonly platform: GitPlatform;
+    /** Repository owner/organization */
+    readonly owner: string;
+    /** Repository name */
+    readonly repo: string;
+    /** Version (tag, branch, or commit) */
+    readonly version: string;
+    /** Full git repository URL */
+    readonly repoUrl: string;
+    /** Package entry point */
+    readonly entryPoint: string;
+}
+
+// ============================================================================
+// Dependency Analysis Types
+// ============================================================================
+
+/**
+ * Node in a dependency tree visualization.
+ */
+export interface DependencyTreeNode {
+    readonly packageKey: string;
+    readonly ref: string;
+    readonly commit: string;
+    readonly dependencies: readonly DependencyTreeNode[];
+    /** Depth in tree (0 = root) */
+    readonly depth: number;
+}
+
+/**
+ * Reverse dependency relationship.
+ */
+export interface ReverseDependency {
+    /** Package that depends on the target */
+    readonly dependentPackage: string;
+    /** Ref of the dependent */
+    readonly ref: string;
+    /** Relationship type */
+    readonly type: 'direct' | 'transitive';
+}
+
+/**
+ * Version update policy.
+ */
+export interface VersionPolicy {
+    readonly policy: 'latest' | 'stable' | 'pinned';
+    readonly ref: string;
+    readonly availableRefs?: readonly string[];
+}
+
+// ============================================================================
+// Governance Types
+// ============================================================================
+
+/** Governance violation type discriminant */
+export type GovernanceViolationType = 
+    | 'blocked-source' 
+    | 'unstable-version' 
+    | 'missing-metadata' 
+    | 'license-violation';
+
+/** Governance violation severity */
+export type GovernanceViolationSeverity = 'error' | 'warning';
+
+/**
+ * A governance policy violation.
+ */
+export interface GovernanceViolation {
+    readonly type: GovernanceViolationType;
+    readonly packageKey: string;
+    readonly message: string;
+    readonly severity: GovernanceViolationSeverity;
+}
+
+/**
+ * Governance metadata for a package (from model.yaml).
+ */
+export interface GovernanceMetadata {
+    readonly team?: string;
+    readonly contact?: string;
+    readonly domain?: string;
+    readonly compliance?: readonly string[];
+}
+
+// ============================================================================
+// Workspace Types
+// ============================================================================
+
+/**
+ * Options for workspace manager initialization.
+ */
+export interface WorkspaceManagerOptions {
+    /** Auto-resolve dependencies on initialization */
+    readonly autoResolve?: boolean;
+    /** Manifest file names to search for */
+    readonly manifestFiles?: readonly string[];
+    /** Lock file names to search for */
+    readonly lockFiles?: readonly string[];
+    /** Allow network access for git operations */
+    readonly allowNetwork?: boolean;
+}