@actiondock/core 2.7.0 → 2.8.0

package/dist/catalog/graph.d.ts

@@ -0,0 +1,190 @@
+import { ActionDockError } from "../errors.js";
+import { type ActionDockLockfile } from "../project/lockfile.js";
+import type { ActionDockManifest, PlaybookDefinition } from "../project/types.js";
+import { type PackageIdentity } from "../runtime/identity.js";
+import { parseSemVer, type SemVer } from "../utils/index.js";
+import { type DiscoveredPackage, type PackageDiscoveryOptions } from "./discovery.js";
+export type { SemVer };
+export { parseSemVer };
+/**
+ * 校验两个语义化版本范围是否兼容并能收敛为单一解析版本。
+ * 遵循设计规范：直接或传递版本范围无法收敛时拒绝并抛出 ACTION_PACKAGE_VERSION_CONFLICT。
+ */
+export declare function areVersionsCompatible(v1: string, v2: string): boolean;
+/**
+ * 版本冲突错误。
+ */
+export declare class ActionPackageVersionConflictError extends ActionDockError {
+    readonly packageId: string;
+    readonly conflicts: Array<{
+        requester: string;
+        rangeOrVersion: string;
+    }>;
+    constructor(packageId: string, conflicts: Array<{
+        requester: string;
+        rangeOrVersion: string;
+    }>);
+}
+/**
+ * 未声明依赖调用拦截错误。
+ */
+export declare class UndeclaredActionDependencyError extends ActionDockError {
+    readonly targetRef: string;
+    readonly caller?: string;
+    constructor(targetRef: string, caller?: string, reason?: string);
+}
+/**
+ * 判定单一 uses 声明项是否命中目标 Action（跨包调用授权单一事实源）。
+ *
+ * 匹配语义（安全铁律，逐字不变）：
+ * - 完全限定名：`<targetPackageId>/<targetActionId>`；
+ * - 包级通配符：`<targetPackageId>/*`；
+ * - 裸包名：`<targetPackageId>`。
+ *
+ * DefaultPackageGraph.canCascadeCall 与 InvocationPolicy.checkUsesAuthorization
+ * 必须统一经由本谓词判定，禁止在调用点另建重复表达式分叉。
+ */
+export declare function isUsesDeclared(use: string, targetPackageId: string, targetActionId: string): boolean;
+/**
+ * 包图拓扑节点定义。
+ */
+export interface PackageNode {
+    /** 包唯一身份标识值对象 */
+    readonly identity: PackageIdentity;
+    /** 逻辑包唯一标识符（等同于 identity.id） */
+    readonly packageId: string;
+    /** 包根目录绝对物理路径 */
+    readonly root: string;
+    /** 包清单规范 */
+    readonly manifest: ActionDockManifest;
+    /** 包清单摘要哈希 */
+    readonly manifestDigest: string;
+    /** 包版本号 */
+    readonly version: string;
+    /** npm 包名或引用规格 */
+    readonly npmPackage: string;
+    /** 直接依赖包标识集合 */
+    readonly directDependencies: Set<string>;
+    /** 传递依赖闭包标识集合 */
+    readonly transitiveDependencies: Set<string>;
+    /** 是否为直接依赖 */
+    readonly isDirect?: boolean;
+    /** 是否为当前工程根包 */
+    readonly isRoot?: boolean;
+}
+/**
+ * 完整包依赖拓扑图 PackageGraph 契约。
+ */
+export interface PackageGraph {
+    /** 当前工程根包身份（若存在） */
+    readonly root?: PackageIdentity;
+    /** 根包标识（快捷访问） */
+    readonly rootPackageId?: string;
+    /** 全局或当前工程全部包节点映射（按 packageId 索引） */
+    readonly packages: Map<string, PackageNode>;
+    /** 根包直接依赖包标识集合 */
+    readonly directDependencyIds: ReadonlySet<string>;
+    /** 根包传递依赖闭包标识集合 */
+    readonly transitiveDependencyIds: ReadonlySet<string>;
+    /** 可见 Playbook 映射 */
+    readonly visiblePlaybooks: Map<string, PlaybookDefinition>;
+    /** 可见 Playbook 委托点名的 Action 集合 */
+    readonly delegatedActions: ReadonlySet<string>;
+    /**
+     * 按包标识获取指定节点。
+     */
+    getPackage(id: string): PackageNode | undefined;
+    /**
+     * 按包标识获取指定节点（统一契约）。
+     */
+    getNode(id: string): PackageNode | undefined;
+    /**
+     * 判定是否存在指定包节点。
+     */
+    hasPackage(id: string): boolean;
+    /**
+     * 判定目标 Action 是否允许作为根调用发起。
+     */
+    canRootCall(targetPackageId: string, targetActionId: string): boolean;
+    /**
+     * 校验根调用权限，不合法时抛出 UndeclaredActionDependencyError。
+     */
+    assertRootCallAllowed(targetPackageId: string, targetActionId: string): void;
+    /**
+     * 判定跨包级联调用是否合法。
+     */
+    canCascadeCall(callerPackageId: string, callerActionId: string, targetPackageId: string, targetActionId: string): boolean;
+    /**
+     * 校验跨包级联调用权限，不合法时抛出 UndeclaredActionDependencyError。
+     */
+    assertCascadeCallAllowed(callerPackageId: string, callerActionId: string, targetPackageId: string, targetActionId: string): void;
+}
+/**
+ * 默认包依赖图实现。
+ */
+export declare class DefaultPackageGraph implements PackageGraph {
+    readonly packages: Map<string, PackageNode>;
+    readonly root?: PackageIdentity;
+    readonly visiblePlaybooks: Map<string, PlaybookDefinition>;
+    readonly delegatedActions: ReadonlySet<string>;
+    constructor(packages: Map<string, PackageNode>, root?: PackageIdentity, visiblePlaybooks?: Map<string, PlaybookDefinition>, delegatedActions?: ReadonlySet<string>);
+    get rootPackageId(): string | undefined;
+    get directDependencyIds(): ReadonlySet<string>;
+    get transitiveDependencyIds(): ReadonlySet<string>;
+    getPackage(id: string): PackageNode | undefined;
+    getNode(id: string): PackageNode | undefined;
+    hasPackage(id: string): boolean;
+    canRootCall(targetPackageId: string, targetActionId: string): boolean;
+    assertRootCallAllowed(targetPackageId: string, targetActionId: string): void;
+    canCascadeCall(callerPackageId: string, callerActionId: string, targetPackageId: string, targetActionId: string): boolean;
+    assertCascadeCallAllowed(callerPackageId: string, callerActionId: string, targetPackageId: string, targetActionId: string): void;
+}
+/**
+ * 包图构建器配置选项。
+ */
+export interface PackageGraphBuilderOptions {
+    /** 预先发现的包集合，若未提供则通过 PackageDiscovery 自动发现 */
+    packages?: DiscoveredPackage[];
+    /** 根工程根目录或根包标识（与 projectRoot 互为别名） */
+    root?: string;
+    /** 当前工程根目录绝对或相对物理路径 */
+    projectRoot?: string;
+    /** 显式根清单 */
+    manifest?: ActionDockManifest;
+    /** 锁文件规范对象（若未显式提供且 projectRoot 存在，则尝试自动读取 actiondock.lock.json） */
+    lockfile?: ActionDockLockfile;
+    /** 是否允许扫描与链接开发软链接包（默认根据 discoveryOptions 判定） */
+    allowDevLinks?: boolean;
+    /** 自定义 ActionDock 主目录路径（用于定位全局链接注册表） */
+    customHome?: string;
+    /** 显式包根目录映射字典或数组 */
+    packageRoots?: Record<string, string> | string[];
+    /** 包发现配置（构建器内部调用 PackageDiscovery 时生效） */
+    discoveryOptions?: PackageDiscoveryOptions;
+    /** 快照代次唯一标识（可选，默认生成 UUID） */
+    generationId?: string;
+}
+/**
+ * 包依赖拓扑图构建器 PackageGraphBuilder。
+ * 输入发现的包集合或工程根目录，统一实施版本冲突检测、lockfile 校验与拓扑图构建。
+ */
+export declare class PackageGraphBuilder {
+    private readonly options;
+    constructor(options?: PackageGraphBuilderOptions);
+    /**
+     * 同步构建包依赖拓扑图（模式 A：显式包集合）。
+     */
+    private buildFromPackages;
+    /**
+     * 同步构建包依赖拓扑图（模式 C：全局包发现）。
+     */
+    private buildFromGlobalDiscovery;
+    /**
+     * 同步构建包依赖拓扑图。
+     */
+    buildSync(): PackageGraph;
+    /**
+     * 异步构建包依赖拓扑图。
+     */
+    build(): Promise<PackageGraph>;
+}