@captain_z/zsk 1.8.2 → 1.8.4

package/dist/core/prepare-sync.js

@@ -5,6 +5,7 @@ import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path
 import { DESIGN_LOCAL_FILE_ORIGIN_KEYS, JIRA_LOCAL_FILE_ORIGIN_KEYS, flattenProjectSources, resolveSourceSnapshot, } from "./config.js";
 import { inferSourceOrigin } from "./origin-detection.js";
 import { describeResource, updateRawIndexes, updateRawManifest } from "./raw-manifest.js";
+import { acquireSourceSnapshot, chooseSourceSnapshotStrategy, createSourceSnapshotContext, } from "./source-snapshot-adapters.js";
 import { getWorkspacePath } from "./workspace-layout.js";
 export function resolvePrepareSyncArtifacts(target, config, runId) {
     const dir = resolve(target, getWorkspacePath(config, "evidenceRoot"), "prepare", runId);
@@ -254,140 +255,119 @@ async function checkAuthEntry(entry, authStatePath, opts) {
     }
 }
 async function syncEntry(target, config, entry, opts) {
-    const source = entry.source;
-    const origin = inferSourceOrigin(source);
-    const snapshot = resolveSourceSnapshot(config, entry);
-    const snapshotPath = resolve(target, snapshot);
-    const previousSnapshotHash = await hashIfExists(snapshotPath);
-    const base = {
-        envelopeVersion: 1,
-        sourceKey: entry.id,
-        sourcePath: entry.path,
-        rawLane: entry.rawLane,
-        provider: origin.provider,
-        origin: origin.ref,
-        snapshot,
-        previousSnapshotHash,
+    const context = await createSourceSnapshotContext(target, config, entry, opts, hashIfExists);
+    return acquireSourceSnapshot(context, {
+        dryRun: skippedDryRunSnapshot,
+        local: syncLocalSnapshot,
+        provider: syncProviderSnapshot,
+        repository: syncRepositorySnapshot,
+        url: syncUrlSnapshot,
+        providerManaged: blockedProviderManagedSnapshot,
+    });
+}
+function skippedDryRunSnapshot(context) {
+    return {
+        ...context.base,
+        strategy: chooseSourceSnapshotStrategy(context.origin.method),
+        status: "skipped",
+        changed: false,
+        reason: "dry-run requested; no snapshot was written",
+        validation: { dryRun: "pass" },
     };
-    if (opts.dryRun) {
-        return {
-            ...base,
-            strategy: chooseStrategy(origin.method),
-            status: "skipped",
-            changed: false,
-            reason: "dry-run requested; no snapshot was written",
-            validation: { dryRun: "pass" },
-        };
+}
+async function syncLocalSnapshot(context) {
+    const { base, entry, source, snapshotPath, previousSnapshotHash, target } = context;
+    const sourcePath = source.origin?.path ?? source.path;
+    if (!sourcePath) {
+        return sourceGap(base, "configured local origin has no path");
     }
-    if (origin.method === "local") {
-        const sourcePath = source.origin?.path ?? source.path;
-        if (!sourcePath) {
-            return sourceGap(base, "configured local origin has no path");
-        }
-        const originPath = resolve(target, sourcePath);
-        if (!(await exists(originPath))) {
-            return sourceGap(base, "configured local origin path does not exist");
-        }
-        await mkdir(dirname(snapshotPath), { recursive: true });
-        if (shouldPreserveMachineReadable(source, originPath, snapshotPath)) {
-            await copyFile(originPath, snapshotPath);
-        }
-        else {
-            await writeFile(snapshotPath, await renderStructuredLocalMarkdown(target, entry, originPath), "utf8");
-        }
-        const snapshotHash = await sha256(snapshotPath);
+    const originPath = resolve(target, sourcePath);
+    if (!(await exists(originPath))) {
+        return sourceGap(base, "configured local origin path does not exist");
+    }
+    await mkdir(dirname(snapshotPath), { recursive: true });
+    if (shouldPreserveMachineReadable(source, originPath, snapshotPath)) {
+        await copyFile(originPath, snapshotPath);
+    }
+    else {
+        await writeFile(snapshotPath, await renderStructuredLocalMarkdown(target, entry, originPath), "utf8");
+    }
+    const snapshotHash = await sha256(snapshotPath);
+    return {
+        ...base,
+        strategy: "local-copy-structured-markdown",
+        status: "materialized",
+        snapshotHash,
+        changed: previousSnapshotHash !== snapshotHash,
+        reason: "local origin copied or materialized into configured snapshot",
+        validation: { sourceExists: "pass", bodyContent: "pass", snapshotWritten: "pass" },
+    };
+}
+async function syncProviderSnapshot(context, providerAdapter) {
+    const { target, config, entry, snapshotPath, previousSnapshotHash, opts, origin } = context;
+    const authStatePath = resolveSelectedAuthStatePath(target, config, opts);
+    const adapterResult = await runProviderAdapter(providerAdapter, target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts);
+    if (!adapterResult)
+        return null;
+    if (adapterResult.status === "blocked-auth" && opts.browser && origin.method === "url") {
+        const browserResult = await fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
         return {
-            ...base,
-            strategy: "local-copy-structured-markdown",
-            status: "materialized",
-            snapshotHash,
-            changed: previousSnapshotHash !== snapshotHash,
-            reason: "local origin copied or materialized into configured snapshot",
-            validation: { sourceExists: "pass", bodyContent: "pass", snapshotWritten: "pass" },
+            ...browserResult,
+            adapter: `${providerAdapter}-browser-fallback`,
+            metadata: cleanMetadata({ providerAdapter, fallbackFrom: adapterResult.strategy }),
         };
     }
-    const providerAdapter = selectProviderAdapter(source, origin);
-    if (providerAdapter) {
-        const authStatePath = resolveSelectedAuthStatePath(target, config, opts);
-        const adapterResult = await runProviderAdapter(providerAdapter, target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts);
-        if (adapterResult) {
-            if (adapterResult.status === "blocked-auth" && opts.browser && origin.method === "url") {
-                const browserResult = await fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
-                return {
-                    ...browserResult,
-                    adapter: `${providerAdapter}-browser-fallback`,
-                    metadata: cleanMetadata({ providerAdapter, fallbackFrom: adapterResult.strategy }),
-                };
-            }
-            return adapterResult;
-        }
-    }
-    if (origin.method === "repository") {
-        await mkdir(dirname(snapshotPath), { recursive: true });
-        const content = renderRepositoryMetadata(entry, origin.ref ?? "");
-        await writeFile(snapshotPath, content, "utf8");
-        const snapshotHash = await sha256(snapshotPath);
+    return adapterResult;
+}
+async function syncRepositorySnapshot(context) {
+    const { base, entry, origin, snapshotPath, previousSnapshotHash } = context;
+    await mkdir(dirname(snapshotPath), { recursive: true });
+    const content = renderRepositoryMetadata(entry, origin.ref ?? "");
+    await writeFile(snapshotPath, content, "utf8");
+    const snapshotHash = await sha256(snapshotPath);
+    return {
+        ...base,
+        strategy: "repository-metadata-only",
+        status: "metadata-only",
+        snapshotHash,
+        changed: previousSnapshotHash !== snapshotHash,
+        reason: "repository origin recorded as metadata; configure contract paths or checkout policy before broad acquisition",
+        validation: { repositoryNotCrawled: "pass", snapshotWritten: "pass" },
+    };
+}
+async function syncUrlSnapshot(context) {
+    const { base, entry, source, origin, target, config, opts, snapshotPath, previousSnapshotHash } = context;
+    if (!opts.allowNetwork) {
         return {
             ...base,
-            strategy: "repository-metadata-only",
-            status: "metadata-only",
-            snapshotHash,
-            changed: previousSnapshotHash !== snapshotHash,
-            reason: "repository origin recorded as metadata; configure contract paths or checkout policy before broad acquisition",
-            validation: { repositoryNotCrawled: "pass", snapshotWritten: "pass" },
+            strategy: "playwright-auth-or-direct-fetch",
+            status: "blocked-auth",
+            changed: false,
+            reason: "remote URL requires --allow-network or a materialized snapshot; Playwright auth helper can create reusable storageState first",
+            validation: { networkAllowed: "fail", previousSnapshotPreserved: previousSnapshotHash ? "pass" : "skipped" },
         };
     }
-    if (origin.method === "url") {
-        if (!opts.allowNetwork) {
-            return {
-                ...base,
-                strategy: "playwright-auth-or-direct-fetch",
-                status: "blocked-auth",
-                changed: false,
-                reason: "remote URL requires --allow-network or a materialized snapshot; Playwright auth helper can create reusable storageState first",
-                validation: { networkAllowed: "fail", previousSnapshotPreserved: previousSnapshotHash ? "pass" : "skipped" },
-            };
-        }
-        const authStatePath = resolveSelectedAuthStatePath(target, config, opts);
-        if (opts.browser) {
-            if (origin.ref && await hasDirectRuntimeAuthForSource(source, origin.ref, authStatePath)) {
-                const direct = await fetchUrlSnapshot(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
-                if (direct.status === "materialized")
-                    return direct;
-            }
-            return fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+    const authStatePath = resolveSelectedAuthStatePath(target, config, opts);
+    if (opts.browser) {
+        if (origin.ref && await hasDirectRuntimeAuthForSource(source, origin.ref, authStatePath)) {
+            const direct = await fetchUrlSnapshot(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+            if (direct.status === "materialized")
+                return direct;
         }
-        return fetchUrlSnapshot(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+        return fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
     }
+    return fetchUrlSnapshot(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+}
+function blockedProviderManagedSnapshot(context) {
     return {
-        ...base,
+        ...context.base,
         strategy: "confirm-acquisition-method",
         status: "blocked-auth",
         changed: false,
         reason: "provider-managed origin needs an explicit acquisition method or exported snapshot",
-        validation: { acquisitionMethodConfirmed: "fail", previousSnapshotPreserved: previousSnapshotHash ? "pass" : "skipped" },
+        validation: { acquisitionMethodConfirmed: "fail", previousSnapshotPreserved: context.previousSnapshotHash ? "pass" : "skipped" },
     };
 }
-function selectProviderAdapter(source, origin) {
-    const keys = [
-        origin.provider,
-        origin.kind,
-        source.origin?.provider,
-        source.origin?.kind,
-        source.kind,
-        source.type,
-    ].map((value) => normalizeAdapterKey(typeof value === "string" ? value : undefined));
-    if (keys.some((value) => value.includes("confluence")))
-        return "confluence";
-    if (keys.some((value) => value.includes("jira")))
-        return "jira";
-    if (keys.some((value) => value.includes("gitlab")))
-        return "gitlab";
-    if (keys.some((value) => ["figma", "modao", "mastergo", "design", "design-asset", "design-source"].includes(value))) {
-        return "design-source";
-    }
-    return undefined;
-}
 async function runProviderAdapter(adapter, target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts) {
     if (adapter === "confluence") {
         return runConfluenceAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts);
@@ -560,10 +540,11 @@ async function runDesignAdapter(target, entry, snapshotPath, previousSnapshotHas
         });
     }
     const url = firstOriginString(entry.source, "apiUrl", "exportUrl", "url") ?? base.origin;
-    if (!url)
-        return null;
+    if (!url) {
+        return sourceGap(base, "design source needs origin.url, origin.apiUrl, origin.exportUrl, or a local exportPath/assetPath/filePath before acquisition", designProviderGapMetadata("missing-provider-locator"));
+    }
     if (!opts.allowNetwork) {
-        return blockedAdapter(base, opts.browser ? "design-browser-render" : "design-api-or-browser", "design source requires --allow-network with token/export URL or --browser storageState acquisition");
+        return blockedAdapter(base, opts.browser ? "design-browser-render" : "design-api-or-browser", "design source requires --allow-network with token/export URL or --browser storageState acquisition", designProviderGapMetadata("network-not-allowed"));
     }
     const directRuntimeAuth = await hasDirectRuntimeAuthForSource(entry.source, url, authStatePath);
     if (opts.browser && !directRuntimeAuth) {
@@ -578,18 +559,18 @@ async function runDesignAdapter(target, entry, snapshotPath, previousSnapshotHas
     if (!fetched.ok) {
         if (opts.browser)
             return fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
-        return blockedAdapter(base, "design-api-or-export", fetched.reason);
+        return blockedAdapter(base, "design-api-or-export", fetched.reason, designProviderGapMetadata("provider-fetch-failed"));
     }
     if (looksLikeLoginPage(fetched.body, fetched.resolvedOrigin)) {
         if (opts.browser)
             return fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
-        return blockedAdapter(base, "design-api-or-export", "design adapter resolved to login/chrome content; previous snapshot was preserved");
+        return blockedAdapter(base, "design-api-or-export", "design adapter resolved to login/chrome content; previous snapshot was preserved", designProviderGapMetadata("provider-auth-blocked"));
     }
     const content = renderDesignMarkdown(fetched.body, fetched.resolvedOrigin, fetched.contentType);
     if (!hasMaterialContent(content)) {
         if (opts.browser)
             return fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
-        return blockedAdapter(base, "design-api-or-export", "design adapter produced no material design content; previous snapshot was preserved");
+        return blockedAdapter(base, "design-api-or-export", "design adapter produced no material design content; previous snapshot was preserved", designProviderGapMetadata("provider-content-incomplete"));
     }
     return writeAdapterSnapshot(target, entry, snapshotPath, previousSnapshotHash, {
         adapter: "design-source",
@@ -1023,6 +1004,11 @@ function renderDesignMarkdown(body, origin, contentType) {
         "",
         fencedBody(JSON.stringify(parsed, null, 2), "application/json"),
         "",
+        "## Reconstruction Guidance",
+        "",
+        "- Semantic category ownership, assets/raw files, reconstruction.json, and known gaps must be reviewed before treating this as complete UE reconstruction evidence.",
+        "- If provider raw payloads or assets are unavailable, record a provider gap and fallback risk in downstream evidence.",
+        "",
     ].filter((line) => typeof line === "string").join("\n");
 }
 function designNodeNames(value) {
@@ -1035,6 +1021,13 @@ function designNodeNames(value) {
     const nested = Array.isArray(children) ? children.flatMap(designNodeNames) : [];
     return current ? [current, ...nested] : nested;
 }
+function designProviderGapMetadata(reason) {
+    return {
+        providerGap: reason,
+        fallbackEvidenceRequired: true,
+        reconstructionRisk: "semantic UE reconstruction needs provider raw payload, assets/raw files, reconstruction.json, and known gaps before downstream design use",
+    };
+}
 function parseCsvRows(value) {
     const rows = parseCsv(value).filter((row) => row.some((cell) => cell.trim().length > 0));
     const headers = rows.shift() ?? [];
@@ -1246,9 +1239,6 @@ function escapeTable(value) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function normalizeAdapterKey(value) {
-    return value?.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") ?? "";
-}
 function renderRepositoryMetadata(entry, repository) {
     return [
         "---",
@@ -1317,15 +1307,6 @@ function shouldPreserveMachineReadable(source, originPath, snapshotPath) {
         [".json", ".yaml", ".yml"].includes(ext) ||
         [".json", ".yaml", ".yml"].includes(snapshotExt));
 }
-function chooseStrategy(method) {
-    if (method === "local")
-        return "local-copy-structured-markdown";
-    if (method === "repository")
-        return "repository-metadata-only";
-    if (method === "url")
-        return "playwright-auth-or-direct-fetch";
-    return "confirm-acquisition-method";
-}
 function renderDownstreamImpact(results) {
     const changed = results.filter((result) => result.changed);
     const blocked = results.filter((result) => ["blocked-auth", "source-gap", "failed"].includes(result.status));
@@ -1375,13 +1356,14 @@ function hasMaterialContent(value) {
     const body = value.replace(/^---[\s\S]*?---/, "").replace(/[#*\-[\]()`\s]/g, "");
     return body.length >= 20;
 }
-function sourceGap(base, reason) {
+function sourceGap(base, reason, metadata) {
     return {
         ...base,
         strategy: "source-gap",
         status: "source-gap",
         changed: false,
         reason,
+        metadata: cleanMetadata(metadata ?? {}),
         validation: { sourceAvailable: "fail" },
     };
 }
@@ -1395,13 +1377,14 @@ function blocked(base, reason) {
         validation: { bodyContent: "fail", previousSnapshotPreserved: base.previousSnapshotHash ? "pass" : "skipped" },
     };
 }
-function blockedAdapter(base, strategy, reason) {
+function blockedAdapter(base, strategy, reason, metadata) {
     return {
         ...base,
         strategy,
         status: "blocked-auth",
         changed: false,
         reason,
+        metadata: cleanMetadata(metadata ?? {}),
         validation: { bodyContent: "fail", previousSnapshotPreserved: base.previousSnapshotHash ? "pass" : "skipped" },
     };
 }