@domainlang/language 0.1.81 → 0.4.0

package/out/services/types.d.ts

@@ -0,0 +1,340 @@
+/**
+ * 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
+ */
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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 declare function isExtendedDependencySpec(dep: DependencySpec): dep is ExtendedDependencySpec;
+/**
+ * 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;
+}
+/**
+ * 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 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>>;
+}
+/**
+ * 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;
+}
+/** 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;
+}
+/**
+ * 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 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[];
+}
+/**
+ * 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;
+}

package/out/services/types.js

@@ -0,0 +1,46 @@
+/**
+ * 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
+ */
+/**
+ * Type guard for extended dependency spec.
+ */
+export function isExtendedDependencySpec(dep) {
+    return typeof dep === 'object' && dep !== null;
+}
+//# sourceMappingURL=types.js.map

package/out/services/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/services/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AA+GH;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAmB;IACxD,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,CAAC;AACnD,CAAC"}

package/out/services/workspace-manager.d.ts

@@ -1,10 +1,5 @@
 import { GitUrlResolver } from './git-url-resolver.js';
-import type { LockFile } from './git-url-resolver.js';
-export interface WorkspaceManagerOptions {
-    readonly autoResolve?: boolean;
-    readonly manifestFiles?: readonly string[];
-    readonly lockFiles?: readonly string[];
-}
+import type { LockFile, ModelManifest, PathAliases, WorkspaceManagerOptions } from './types.js';
 /**
  * Coordinates workspace discovery, lock file lifecycle management, and git resolver configuration.
  */
@@ -33,6 +28,11 @@ export declare class WorkspaceManager {
      * Resolves the manifest file path within the workspace, if present.
      */
     getManifestPath(): Promise<string | undefined>;
+    /**
+     * Returns the parsed manifest when present, otherwise undefined.
+     * Uses cached contents when unchanged on disk.
+     */
+    getManifest(): Promise<ModelManifest | undefined>;
     /**
      * Returns the cached lock file or triggers resolution when missing.
      */
@@ -45,6 +45,24 @@ export declare class WorkspaceManager {
      * Reloads the lock file from disk, updating the git resolver.
      */
     refreshLockFile(): Promise<LockFile | undefined>;
+    /**
+     * Invalidates all cached data (manifest and lock file).
+     * Call this when config files change externally (e.g., from CLI commands).
+     *
+     * After invalidation, the next call to getManifest() or getLockFile()
+     * will re-read from disk.
+     */
+    invalidateCache(): void;
+    /**
+     * Invalidates only the manifest cache.
+     * Call this when model.yaml changes.
+     */
+    invalidateManifestCache(): void;
+    /**
+     * Invalidates only the lock file cache.
+     * Call this when model.lock changes.
+     */
+    invalidateLockCache(): void;
     /**
      * Provides the shared git URL resolver configured with the current lock file.
      */
@@ -54,12 +72,25 @@ export declare class WorkspaceManager {
      */
     regenerateLockFile(): Promise<LockFile>;
     /**
-     * Resolves a manifest dependency alias to its git import string.
+     * Returns the path aliases from the manifest, if present.
+     */
+    getPathAliases(): Promise<PathAliases | undefined>;
+    /**
+     * Normalizes a dependency entry to its extended form.
+     * Handles both short form (string version) and extended form (object).
+     *
+     * In the new format, the key IS the owner/package, so source is derived from key
+     * ONLY for git dependencies (not for path-based local dependencies).
+     */
+    private normalizeDependency;
+    /**
+     * Resolves a manifest dependency to its git import string.
      *
-     * @param aliasPath - Alias from import statement (may include subpaths)
-     * @returns Resolved git import string or undefined when alias is unknown
+     * NEW FORMAT (PRS-010): Dependencies are keyed by owner/package directly
+     * @param specifier - Import specifier (owner/package format, may include subpaths)
+     * @returns Resolved git import string or undefined when not found
      */
-    resolveDependencyImport(aliasPath: string): Promise<string | undefined>;
+    resolveDependencyImport(specifier: string): Promise<string | undefined>;
     private performInitialization;
     private ensureInitialized;
     private applyLockFile;
@@ -69,6 +100,22 @@ export declare class WorkspaceManager {
     private loadLockFileFromDisk;
     private tryReadLockFile;
     private loadManifest;
+    /**
+     * Validates manifest structure and dependency configurations.
+     * Throws detailed errors for invalid manifests.
+     *
+     * Supports both new format (owner/package: version) and extended format.
+     */
+    private validateManifest;
+    /**
+     * Validates path aliases for security and correctness.
+     */
+    private validatePathAliases;
+    /**
+     * Validates local path dependencies for security.
+     * Ensures paths don't escape workspace boundary.
+     */
+    private validateLocalPath;
     private parseJsonLockFile;
     private findWorkspaceRoot;
     private containsManifest;