@treeseed/sdk 0.11.0 → 0.12.4

package/dist/guarantees/index.d.ts

@@ -0,0 +1,425 @@
+export declare const TREESEED_GUARANTEE_SCHEMA_VERSION: "treeseed.guarantee/v1";
+export declare const TREESEED_GUARANTEE_VERIFIERS_SCHEMA_VERSION: "treeseed.guarantee-verifiers/v1";
+export type TreeseedGuaranteeSchemaVersion = typeof TREESEED_GUARANTEE_SCHEMA_VERSION;
+export type TreeseedGuaranteeVerifiersSchemaVersion = typeof TREESEED_GUARANTEE_VERIFIERS_SCHEMA_VERSION;
+export type TreeseedGuaranteeGate = 'smoke' | 'core' | 'release' | 'security' | 'migration' | 'demo' | 'backlog' | 'future';
+export type TreeseedGuaranteeStatus = 'active' | 'planned' | 'blocked' | 'backlog' | 'deprecated';
+export type TreeseedGuaranteeSurface = 'admin-ui' | 'agent-runtime' | 'api-control-plane' | 'market-ui' | 'cli' | 'scene' | 'content-runtime';
+export type TreeseedGuaranteeDevice = 'desktop_chromium' | 'desktop_firefox' | 'desktop_webkit' | 'tablet_chromium' | 'mobile_chromium' | 'mobile_webkit';
+export type TreeseedGuaranteeDiagnosticSeverity = 'error' | 'warning';
+export type TreeseedGuaranteeDiagnostic = {
+    severity: TreeseedGuaranteeDiagnosticSeverity;
+    code: string;
+    message: string;
+    path?: string;
+    sourcePath?: string;
+};
+export type TreeseedGuaranteeVerifierContract = {
+    required?: boolean;
+    verifierRefs?: string[];
+};
+export type TreeseedGuaranteeApiContract = TreeseedGuaranteeVerifierContract;
+export type TreeseedGuaranteeSceneContract = {
+    required?: boolean;
+    manifest?: string;
+    mode?: {
+        acceptance?: boolean;
+        demo?: boolean;
+        training?: boolean;
+    };
+    entryRoute?: string;
+    componentContract?: string;
+    expectedEvidence?: string[];
+};
+export type TreeseedGuaranteeNegativeCase = {
+    id: string;
+    actor?: string;
+    verifierRefs?: string[];
+    notes?: string[];
+};
+export type TreeseedGuaranteeDependencies = {
+    journeys?: number[];
+    guarantees?: string[];
+};
+export type TreeseedGuaranteeRunContract = {
+    timeoutSeconds?: number;
+    allowSkipped?: boolean;
+    requiredForRelease?: boolean;
+};
+export type TreeseedGuaranteeManifest = {
+    schemaVersion: TreeseedGuaranteeSchemaVersion;
+    id: string;
+    journeyIndex?: number;
+    type: string;
+    subtype: string;
+    journey: string;
+    ownerPackage: string;
+    surface?: TreeseedGuaranteeSurface;
+    summary: string;
+    status: TreeseedGuaranteeStatus;
+    run?: TreeseedGuaranteeRunContract;
+    dependencies: TreeseedGuaranteeDependencies;
+    actors: {
+        allowed: string[];
+        forbidden: string[];
+    };
+    devices: {
+        required: TreeseedGuaranteeDevice[];
+        optional?: TreeseedGuaranteeDevice[];
+    };
+    gates: TreeseedGuaranteeGate[];
+    preconditions: {
+        fixtures?: string[];
+        notes?: string[];
+    };
+    scene?: TreeseedGuaranteeSceneContract;
+    api?: TreeseedGuaranteeApiContract;
+    content?: TreeseedGuaranteeVerifierContract;
+    audit?: TreeseedGuaranteeVerifierContract;
+    negativeCases?: TreeseedGuaranteeNegativeCase[];
+    evidence: {
+        required: string[];
+        optional?: string[];
+    };
+    notes?: string[];
+};
+export type TreeseedLoadedGuarantee = {
+    sourcePath: string;
+    relativePath: string;
+    packageRoot: string;
+    ownerPackage: string;
+    manifest: TreeseedGuaranteeManifest | null;
+    diagnostics: TreeseedGuaranteeDiagnostic[];
+};
+export type TreeseedGuaranteeVerifierKind = 'apiAcceptanceCase' | 'vitestCase' | 'nodeScript' | 'packageScript' | 'scene' | 'manualEvidence' | 'todo';
+export type TreeseedGuaranteeVerifierDefinition = {
+    kind: TreeseedGuaranteeVerifierKind;
+    ownerPackage?: string;
+    spec?: string;
+    caseId?: string;
+    command?: string;
+    args?: string[];
+    testFile?: string;
+    testName?: string;
+    cwd?: string;
+    timeoutSeconds?: number;
+    evidence?: string[];
+    description?: string;
+};
+export type TreeseedGuaranteeVerifierRegistry = {
+    schemaVersion: TreeseedGuaranteeVerifiersSchemaVersion;
+    ownerPackage: string;
+    verifiers: Record<string, TreeseedGuaranteeVerifierDefinition>;
+};
+export type TreeseedLoadedGuaranteeVerifierRegistry = {
+    sourcePath: string;
+    ownerPackage: string;
+    registry: TreeseedGuaranteeVerifierRegistry | null;
+    diagnostics: TreeseedGuaranteeDiagnostic[];
+};
+export type TreeseedGuaranteeFilter = {
+    gate?: TreeseedGuaranteeGate;
+    type?: string;
+    subtype?: string;
+    ownerPackage?: string;
+    status?: TreeseedGuaranteeStatus;
+    ids?: string[];
+    journeyIndexes?: number[];
+};
+export type TreeseedGuaranteeRegistryReport = {
+    ok: boolean;
+    workspaceRoot: string;
+    guarantees: TreeseedLoadedGuarantee[];
+    verifierRegistries: TreeseedLoadedGuaranteeVerifierRegistry[];
+    diagnostics: TreeseedGuaranteeDiagnostic[];
+    counts: {
+        total: number;
+        valid: number;
+        selected?: number;
+        errors: number;
+        warnings: number;
+    };
+};
+export type TreeseedGuaranteePlanEntry = {
+    id: string;
+    journeyIndex?: number;
+    type: string;
+    subtype: string;
+    journey: string;
+    ownerPackage: string;
+    surface?: TreeseedGuaranteeSurface;
+    status: TreeseedGuaranteeStatus;
+    gates: TreeseedGuaranteeGate[];
+    sourcePath: string;
+    selected: boolean;
+    dependency: boolean;
+    sceneManifest?: string;
+    apiVerifierRefs: string[];
+    contentVerifierRefs: string[];
+    auditVerifierRefs: string[];
+    evidenceRequired: string[];
+};
+export type TreeseedGuaranteeVerifierResolution = {
+    ref: string;
+    resolved: boolean;
+    sourcePath?: string;
+    ownerPackage?: string;
+    definition?: TreeseedGuaranteeVerifierDefinition;
+};
+export type TreeseedGuaranteeVerifierResolutionReport = {
+    ok: boolean;
+    resolutions: TreeseedGuaranteeVerifierResolution[];
+    diagnostics: TreeseedGuaranteeDiagnostic[];
+};
+export type TreeseedGuaranteeRunStatus = 'passed' | 'failed' | 'skipped' | 'blocked';
+export type TreeseedGuaranteeRunStep = {
+    id: string;
+    kind: 'scene' | 'api' | 'content' | 'audit' | 'negative-case' | 'verifier';
+    status: TreeseedGuaranteeRunStatus;
+    ref?: string;
+    summary?: string;
+    evidence?: string[];
+    diagnostics?: TreeseedGuaranteeDiagnostic[];
+    startedAt?: string;
+    completedAt?: string;
+};
+export type TreeseedGuaranteeRunResult = {
+    id: string;
+    journeyIndex?: number;
+    type: string;
+    subtype: string;
+    journey: string;
+    ownerPackage: string;
+    status: TreeseedGuaranteeRunStatus;
+    selected: boolean;
+    dependency: boolean;
+    sourcePath: string;
+    startedAt: string;
+    completedAt: string;
+    steps: TreeseedGuaranteeRunStep[];
+    evidence: string[];
+    diagnostics: TreeseedGuaranteeDiagnostic[];
+};
+export type TreeseedGuaranteeRunReport = {
+    ok: boolean;
+    runId: string;
+    workspaceRoot: string;
+    environment: string;
+    filter: TreeseedGuaranteeFilter;
+    startedAt: string;
+    completedAt: string;
+    outputRoot: string;
+    plan: TreeseedGuaranteePlanReport;
+    results: TreeseedGuaranteeRunResult[];
+    diagnostics: TreeseedGuaranteeDiagnostic[];
+    counts: {
+        planned: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+        blocked: number;
+        releaseBlockingFailures: number;
+    };
+};
+export type TreeseedGuaranteeReportWriteResult = {
+    ok: boolean;
+    outputRoot: string;
+    planPath: string;
+    reportPath: string;
+    markdownPath: string;
+    csvPath: string;
+    diagnostics: TreeseedGuaranteeDiagnostic[];
+};
+export type TreeseedGuaranteeVerifierExecutionInput = {
+    workspaceRoot: string;
+    environment: string;
+    runId: string;
+    outputRoot: string;
+    guarantee: TreeseedLoadedGuarantee & {
+        manifest: TreeseedGuaranteeManifest;
+    };
+    ref: string;
+    definition: TreeseedGuaranteeVerifierDefinition;
+    kind: TreeseedGuaranteeRunStep['kind'];
+};
+export type TreeseedGuaranteeVerifierExecutionResult = {
+    status: TreeseedGuaranteeRunStatus;
+    summary?: string;
+    evidence?: string[];
+    diagnostics?: TreeseedGuaranteeDiagnostic[];
+};
+export type TreeseedGuaranteeVerifierExecutor = (input: TreeseedGuaranteeVerifierExecutionInput) => Promise<TreeseedGuaranteeVerifierExecutionResult>;
+export type TreeseedGuaranteeSceneExecutionInput = {
+    workspaceRoot: string;
+    environment: string;
+    runId: string;
+    outputRoot: string;
+    guarantee: TreeseedLoadedGuarantee & {
+        manifest: TreeseedGuaranteeManifest;
+    };
+    scenePath: string;
+    record?: boolean;
+    device?: string;
+};
+export type TreeseedGuaranteeSceneExecutor = (input: TreeseedGuaranteeSceneExecutionInput) => Promise<TreeseedGuaranteeVerifierExecutionResult>;
+export type TreeseedGuaranteePlanReport = {
+    ok: boolean;
+    workspaceRoot: string;
+    filter: TreeseedGuaranteeFilter;
+    environment: string;
+    entries: TreeseedGuaranteePlanEntry[];
+    diagnostics: TreeseedGuaranteeDiagnostic[];
+    counts: {
+        total: number;
+        selected: number;
+        withDependencies: number;
+        errors: number;
+        warnings: number;
+    };
+};
+export declare function normalizeTreeseedGuaranteeTaxonomy(value: string): string;
+export declare function slugifyTreeseedGuaranteeJourney(value: string): string;
+export declare function loadTreeseedGuaranteeManifest(input: {
+    workspaceRoot: string;
+    path: string;
+}): TreeseedLoadedGuarantee;
+export declare function loadTreeseedGuaranteeVerifierRegistry(input: {
+    workspaceRoot: string;
+    path: string;
+}): TreeseedLoadedGuaranteeVerifierRegistry;
+export declare function discoverTreeseedGuarantees(input?: {
+    workspaceRoot: string;
+    filter?: TreeseedGuaranteeFilter;
+}): TreeseedGuaranteeRegistryReport;
+export declare function validateTreeseedGuarantee(input: {
+    workspaceRoot: string;
+    path: string;
+}): TreeseedLoadedGuarantee;
+export declare function filterTreeseedGuarantees(input: {
+    guarantees: TreeseedLoadedGuarantee[];
+    filter?: TreeseedGuaranteeFilter;
+    includeDependencies?: boolean;
+}): (TreeseedLoadedGuarantee & {
+    manifest: TreeseedGuaranteeManifest;
+})[];
+export declare function validateTreeseedGuaranteeRegistry(input: {
+    workspaceRoot: string;
+    guarantees: TreeseedLoadedGuarantee[];
+    verifierRegistries?: TreeseedLoadedGuaranteeVerifierRegistry[];
+    filter?: TreeseedGuaranteeFilter;
+}): TreeseedGuaranteeRegistryReport;
+export declare function planTreeseedGuarantees(input: {
+    workspaceRoot: string;
+    filter?: TreeseedGuaranteeFilter;
+    environment?: string;
+    includeDependencies?: boolean;
+}): TreeseedGuaranteePlanReport;
+export declare function exportTreeseedGuaranteesCsv(input: {
+    guarantees: TreeseedLoadedGuarantee[];
+    filter?: TreeseedGuaranteeFilter;
+}): string;
+export declare function exportTreeseedGuaranteesJson(input: {
+    registry: TreeseedGuaranteeRegistryReport;
+    filter?: TreeseedGuaranteeFilter;
+}): {
+    schemaVersion: string;
+    generatedAt: string;
+    workspaceRoot: string;
+    guarantees: {
+        schemaVersion: TreeseedGuaranteeSchemaVersion;
+        id: string;
+        journeyIndex?: number;
+        type: string;
+        subtype: string;
+        journey: string;
+        ownerPackage: string;
+        surface?: TreeseedGuaranteeSurface;
+        summary: string;
+        status: TreeseedGuaranteeStatus;
+        run?: TreeseedGuaranteeRunContract;
+        dependencies: TreeseedGuaranteeDependencies;
+        actors: {
+            allowed: string[];
+            forbidden: string[];
+        };
+        devices: {
+            required: TreeseedGuaranteeDevice[];
+            optional?: TreeseedGuaranteeDevice[];
+        };
+        gates: TreeseedGuaranteeGate[];
+        preconditions: {
+            fixtures?: string[];
+            notes?: string[];
+        };
+        scene?: TreeseedGuaranteeSceneContract;
+        api?: TreeseedGuaranteeApiContract;
+        content?: TreeseedGuaranteeVerifierContract;
+        audit?: TreeseedGuaranteeVerifierContract;
+        negativeCases?: TreeseedGuaranteeNegativeCase[];
+        evidence: {
+            required: string[];
+            optional?: string[];
+        };
+        notes?: string[];
+        sourcePath: string;
+    }[];
+};
+export declare function exportTreeseedGuaranteesMarkdown(input: {
+    registry: TreeseedGuaranteeRegistryReport;
+    filter?: TreeseedGuaranteeFilter;
+}): string;
+export declare function writeTreeseedGuaranteesExport(input: {
+    workspaceRoot: string;
+    format: 'csv' | 'json' | 'markdown';
+    output: string;
+    filter?: TreeseedGuaranteeFilter;
+}): {
+    ok: boolean;
+    outputPath: string;
+    registry: TreeseedGuaranteeRegistryReport;
+};
+export declare function resolveTreeseedGuaranteeVerifierRefs(input: {
+    refs: string[];
+    verifierRegistries: TreeseedLoadedGuaranteeVerifierRegistry[];
+    status?: TreeseedGuaranteeStatus;
+    sourcePath?: string;
+}): TreeseedGuaranteeVerifierResolutionReport;
+export declare function writeTreeseedGuaranteeRunReport(input: {
+    report: TreeseedGuaranteeRunReport;
+    registry?: TreeseedGuaranteeRegistryReport;
+}): TreeseedGuaranteeReportWriteResult;
+export declare function runTreeseedGuarantees(input: {
+    workspaceRoot: string;
+    filter?: TreeseedGuaranteeFilter;
+    environment?: string;
+    outputRoot?: string;
+    includeDependencies?: boolean;
+    includePlanned?: boolean;
+    failOnSkippedReleaseGuarantees?: boolean;
+    record?: boolean;
+    device?: string;
+    evidenceTarget?: 'local' | 'ci' | 'release';
+    sceneExecutor?: TreeseedGuaranteeSceneExecutor;
+    verifierExecutor?: TreeseedGuaranteeVerifierExecutor;
+    now?: Date;
+}): Promise<TreeseedGuaranteeRunReport>;
+export declare function createTreeseedGuaranteeStatusReport(input: {
+    workspaceRoot: string;
+}): {
+    ok: boolean;
+    workspaceRoot: string;
+    guaranteeRoots: string[];
+    counts: {
+        total: number;
+        valid: number;
+        selected?: number;
+        errors: number;
+        warnings: number;
+    };
+    byType: Record<string, number>;
+    byStatus: Record<string, number>;
+    verifierRegistries: number;
+    diagnostics: TreeseedGuaranteeDiagnostic[];
+};
+export declare function assertPathInsideWorkspace(workspaceRoot: string, path: string): string;
+export declare function fileExists(path: string): boolean;