@devtrack-solution/codesdd 1.2.2 → 1.2.3

package/dist/core/sdd/backlog-conflict-policy.js

@@ -0,0 +1,230 @@
+import { createHash } from 'node:crypto';
+const POLICY_VERSION = 'v1';
+export function classifyBacklogSyncConflict(input) {
+    const canonical = normalizeCanonical(input.canonical);
+    const sourceOfTruth = input.source_of_truth ?? 'codesdd';
+    const canonicalFingerprint = fingerprintBacklogSyncFields(canonical);
+    const decisions = [
+        {
+            code: 'source-of-truth.codesdd',
+            severity: 'info',
+            message: 'CodeSDD canonical state is authoritative for backlog sync decisions.',
+            source_of_truth: 'codesdd',
+        },
+    ];
+    if (sourceOfTruth !== 'codesdd') {
+        decisions.push({
+            code: 'source-of-truth.unsupported',
+            severity: 'error',
+            message: 'Backlog sync only supports CodeSDD as the source of truth.',
+            source_of_truth: 'codesdd',
+            external_value: sourceOfTruth,
+        });
+        return buildResult('manual-review', input.provider, canonical.ref, canonicalFingerprint, decisions);
+    }
+    if (!input.external) {
+        decisions.push({
+            code: 'external.missing',
+            severity: 'info',
+            message: 'No external work item is linked; create a provider item from canonical CodeSDD state.',
+            source_of_truth: 'codesdd',
+        });
+        return buildResult('create', input.provider, canonical.ref, canonicalFingerprint, decisions);
+    }
+    const external = normalizeExternal(input.external);
+    if (external.provider !== input.provider) {
+        decisions.push({
+            code: 'provider.mismatch',
+            severity: 'error',
+            message: 'External work item belongs to a different provider than the sync request.',
+            source_of_truth: 'codesdd',
+            canonical_value: input.provider,
+            external_value: external.provider,
+        });
+        return buildResult('manual-review', input.provider, canonical.ref, canonicalFingerprint, decisions);
+    }
+    if (external.canonical_ref && external.canonical_ref !== canonical.ref) {
+        decisions.push({
+            code: 'canonical-ref.mismatch',
+            severity: 'error',
+            message: 'External work item points at a different CodeSDD reference.',
+            field: 'canonical_ref',
+            source_of_truth: 'codesdd',
+            canonical_value: canonical.ref,
+            external_value: external.canonical_ref,
+        });
+        return buildResult('manual-review', input.provider, canonical.ref, canonicalFingerprint, decisions);
+    }
+    const diffs = diffSyncFields(canonical, external);
+    for (const diff of diffs) {
+        decisions.push({
+            code: 'field.diff',
+            severity: 'warning',
+            message: `External field ${diff.field} differs from canonical CodeSDD state.`,
+            field: diff.field,
+            source_of_truth: 'codesdd',
+            canonical_value: diff.canonical_value,
+            external_value: diff.external_value,
+        });
+    }
+    if (diffs.length === 0 && external.codesdd_fingerprint === canonicalFingerprint) {
+        decisions.push({
+            code: 'sync.clean',
+            severity: 'info',
+            message: 'External work item already matches the canonical CodeSDD fingerprint.',
+            source_of_truth: 'codesdd',
+        });
+        return buildResult('none', input.provider, canonical.ref, canonicalFingerprint, decisions);
+    }
+    if (diffs.length === 0 && !external.codesdd_fingerprint) {
+        decisions.push({
+            code: 'sync.equivalent-without-fingerprint',
+            severity: 'info',
+            message: 'External work item fields match canonical state, but provider fingerprint metadata is absent.',
+            source_of_truth: 'codesdd',
+        });
+        return buildResult('update', input.provider, canonical.ref, canonicalFingerprint, decisions);
+    }
+    const lastSyncedAt = latestDate(canonical.last_synced_at, external.last_synced_at);
+    const canonicalChanged = changedAfter(canonical.updated_at, lastSyncedAt);
+    const externalChanged = changedAfter(external.updated_at, lastSyncedAt);
+    if (diffs.length > 0 && canonicalChanged && externalChanged) {
+        decisions.push({
+            code: 'drift.concurrent',
+            severity: 'error',
+            message: 'Both canonical and external items changed after the last sync; manual review is required.',
+            source_of_truth: 'codesdd',
+        });
+        return buildResult('manual-review', input.provider, canonical.ref, canonicalFingerprint, decisions);
+    }
+    if (diffs.length > 0 && canonicalChanged) {
+        decisions.push({
+            code: 'canonical.drift',
+            severity: 'warning',
+            message: 'Canonical CodeSDD state changed after the last sync; push canonical state to the provider.',
+            source_of_truth: 'codesdd',
+        });
+        return buildResult('canonical-drift', input.provider, canonical.ref, canonicalFingerprint, decisions);
+    }
+    if (diffs.length > 0 && externalChanged) {
+        decisions.push({
+            code: 'external.stale',
+            severity: 'warning',
+            message: 'External work item drifted from CodeSDD; overwrite from canonical state unless reviewed.',
+            source_of_truth: 'codesdd',
+        });
+        return buildResult('stale-external', input.provider, canonical.ref, canonicalFingerprint, decisions);
+    }
+    decisions.push({
+        code: 'sync.update-required',
+        severity: 'warning',
+        message: 'External work item differs from canonical CodeSDD state and should be updated.',
+        source_of_truth: 'codesdd',
+    });
+    return buildResult('update', input.provider, canonical.ref, canonicalFingerprint, decisions);
+}
+export function buildBacklogSyncIdempotencyKey(input) {
+    return ['codesdd-backlog-sync', POLICY_VERSION, input.provider, input.canonical_ref, input.operation].join(':');
+}
+export function fingerprintBacklogSyncFields(fields) {
+    return `sha256:${createHash('sha256').update(stableStringify(normalizeFieldSet(fields))).digest('hex')}`;
+}
+function buildResult(classification, provider, canonicalRef, canonicalFingerprint, decisions) {
+    const operation = operationForClassification(classification);
+    return {
+        classification,
+        operation,
+        idempotency_key: buildBacklogSyncIdempotencyKey({ provider, canonical_ref: canonicalRef, operation }),
+        canonical_fingerprint: canonicalFingerprint,
+        decisions,
+    };
+}
+function operationForClassification(classification) {
+    if (classification === 'none')
+        return 'noop';
+    if (classification === 'create')
+        return 'create';
+    if (classification === 'manual-review')
+        return 'manual-review';
+    return 'update';
+}
+function normalizeCanonical(item) {
+    return {
+        ...item,
+        ...normalizeFieldSet(item),
+    };
+}
+function normalizeExternal(item) {
+    return {
+        ...item,
+        title: normalizeString(item.title),
+        status: normalizeString(item.status),
+        parent_ref: normalizeOptionalString(item.parent_ref),
+        labels: normalizeLabels(item.labels),
+    };
+}
+function normalizeFieldSet(fields) {
+    return {
+        title: normalizeString(fields.title),
+        status: normalizeString(fields.status),
+        parent_ref: normalizeOptionalString(fields.parent_ref) ?? '',
+        labels: normalizeLabels(fields.labels),
+    };
+}
+function normalizeString(value) {
+    return (value ?? '').trim();
+}
+function normalizeOptionalString(value) {
+    const normalized = normalizeString(value);
+    return normalized.length > 0 ? normalized : undefined;
+}
+function normalizeLabels(labels) {
+    return Array.from(new Set((labels ?? []).map((label) => label.trim()).filter(Boolean))).sort((left, right) => left.localeCompare(right));
+}
+function diffSyncFields(canonical, external) {
+    const canonicalFields = normalizeFieldSet(canonical);
+    const externalFields = normalizeFieldSet({
+        title: external.title ?? '',
+        status: external.status ?? '',
+        parent_ref: external.parent_ref,
+        labels: external.labels,
+    });
+    const diffs = [];
+    for (const field of ['title', 'status', 'parent_ref']) {
+        if (canonicalFields[field] !== externalFields[field]) {
+            diffs.push({ field, canonical_value: canonicalFields[field], external_value: externalFields[field] });
+        }
+    }
+    if (stableStringify(canonicalFields.labels) !== stableStringify(externalFields.labels)) {
+        diffs.push({ field: 'labels', canonical_value: canonicalFields.labels, external_value: externalFields.labels });
+    }
+    return diffs;
+}
+function latestDate(left, right) {
+    if (!left)
+        return right;
+    if (!right)
+        return left;
+    return Date.parse(left) >= Date.parse(right) ? left : right;
+}
+function changedAfter(candidate, baseline) {
+    if (!candidate || !baseline)
+        return false;
+    const candidateTime = Date.parse(candidate);
+    const baselineTime = Date.parse(baseline);
+    return Number.isFinite(candidateTime) && Number.isFinite(baselineTime) && candidateTime > baselineTime;
+}
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+//# sourceMappingURL=backlog-conflict-policy.js.map

package/dist/core/sdd/backlog-projection.d.ts

@@ -0,0 +1,8 @@
+import { type BacklogProjectionPlan, type BacklogProviderContract, type BacklogProviderContractInput, type CanonicalBacklogItem } from './backlog-provider-contract.js';
+export declare function builtInAzureDevOpsBacklogContract(): BacklogProviderContract;
+export declare function buildAzureDevOpsBacklogProjectionPlan(input: {
+    items: CanonicalBacklogItem[];
+    created_at?: string;
+    contract?: BacklogProviderContractInput;
+}): BacklogProjectionPlan;
+//# sourceMappingURL=backlog-projection.d.ts.map

package/dist/core/sdd/backlog-projection.js

@@ -0,0 +1,89 @@
+import { backlogProjectionPlanSchema, buildBacklogProjectionItem, createBacklogProviderContract, } from './backlog-provider-contract.js';
+const AZURE_DEVOPS_EXTERNAL_TYPES = {
+    epic: 'Epic',
+    feature: 'User Story',
+};
+export function builtInAzureDevOpsBacklogContract() {
+    return createBacklogProviderContract({
+        schema_version: 1,
+        provider: 'azure-devops',
+        adapter_id: 'azure-devops',
+        label: 'Azure DevOps Boards',
+        status: 'experimental',
+        auth: {
+            mode: 'pat',
+            required_env: ['AZURE_DEVOPS_EXT_PAT'],
+            secret_fields: ['AZURE_DEVOPS_EXT_PAT'],
+        },
+        capabilities: [
+            {
+                operation: 'create',
+                entity_kinds: ['epic', 'feature'],
+                dry_run: true,
+                apply: false,
+                idempotent: true,
+                required_fields: ['System.Title', 'System.State', 'Custom.CodeSDDRef'],
+            },
+            {
+                operation: 'link',
+                entity_kinds: ['epic', 'feature'],
+                dry_run: true,
+                apply: false,
+                idempotent: true,
+            },
+        ],
+        mapping: {
+            external_project_field: 'System.TeamProject',
+            external_id_field: 'System.Id',
+            external_url_field: 'System.Url',
+            canonical_ref_field: 'Custom.CodeSDDRef',
+            parent_ref_field: 'Custom.CodeSDDParentRef',
+            entity_type_field: 'Custom.CodeSDDEntityType',
+            title_field: 'System.Title',
+            status_field: 'System.State',
+        },
+        canonical_state_boundary: {
+            source_of_truth: 'codesdd',
+            state_paths: ['.sdd/state/*.yaml'],
+            external_state_authoritative: false,
+            hidden_state_allowed: false,
+        },
+        governance: {
+            owner: 'platform-architecture',
+            sync_requires_dry_run: true,
+            mutation_requires_approval: true,
+            audit_event: 'codesdd.backlog.projection',
+        },
+    });
+}
+export function buildAzureDevOpsBacklogProjectionPlan(input) {
+    const contract = input.contract
+        ? createBacklogProviderContract(input.contract)
+        : builtInAzureDevOpsBacklogContract();
+    if (contract.provider !== 'azure-devops') {
+        throw new Error(`Azure DevOps projection planner requires provider azure-devops, received ${contract.provider}.`);
+    }
+    const projectedItems = input.items.map((item) => {
+        const externalType = AZURE_DEVOPS_EXTERNAL_TYPES[item.kind];
+        if (!externalType) {
+            throw new Error(`Azure DevOps projection planner supports only epic and feature items, received ${item.kind}.`);
+        }
+        return buildBacklogProjectionItem({
+            contract,
+            item,
+            external_type: externalType,
+            operation: 'create',
+        });
+    });
+    return backlogProjectionPlanSchema.parse({
+        schema_version: 1,
+        created_at: input.created_at ?? new Date().toISOString(),
+        provider: 'azure-devops',
+        mode: 'dry-run',
+        direction: 'push',
+        source_of_truth: 'codesdd',
+        items: projectedItems,
+        warnings: [],
+    });
+}
+//# sourceMappingURL=backlog-projection.js.map

package/dist/core/sdd/backlog-provider-contract.d.ts

@@ -0,0 +1,252 @@
+import { z } from 'zod';
+export declare const backlogProviderIdSchema: z.ZodEnum<{
+    generic: "generic";
+    "azure-devops": "azure-devops";
+    jira: "jira";
+    trello: "trello";
+    confluence: "confluence";
+    asana: "asana";
+}>;
+export declare const backlogEntityKindSchema: z.ZodEnum<{
+    epic: "epic";
+    feature: "feature";
+    insight: "insight";
+    debate: "debate";
+    task: "task";
+}>;
+export declare const backlogProviderOperationSchema: z.ZodEnum<{
+    link: "link";
+    update: "update";
+    create: "create";
+    query: "query";
+}>;
+export declare const backlogProjectionModeSchema: z.ZodEnum<{
+    apply: "apply";
+    "dry-run": "dry-run";
+}>;
+export declare const backlogProjectionDirectionSchema: z.ZodEnum<{
+    push: "push";
+    pull: "pull";
+    bidirectional: "bidirectional";
+}>;
+export declare const backlogAuthModeSchema: z.ZodEnum<{
+    none: "none";
+    pat: "pat";
+    oauth: "oauth";
+    "managed-identity": "managed-identity";
+    "app-installation": "app-installation";
+}>;
+export declare const backlogProviderCapabilitySchema: z.ZodObject<{
+    operation: z.ZodEnum<{
+        link: "link";
+        update: "update";
+        create: "create";
+        query: "query";
+    }>;
+    entity_kinds: z.ZodArray<z.ZodEnum<{
+        epic: "epic";
+        feature: "feature";
+        insight: "insight";
+        debate: "debate";
+        task: "task";
+    }>>;
+    dry_run: z.ZodDefault<z.ZodBoolean>;
+    apply: z.ZodDefault<z.ZodBoolean>;
+    idempotent: z.ZodDefault<z.ZodBoolean>;
+    required_fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const backlogProviderContractSchema: z.ZodObject<{
+    schema_version: z.ZodDefault<z.ZodLiteral<1>>;
+    provider: z.ZodEnum<{
+        generic: "generic";
+        "azure-devops": "azure-devops";
+        jira: "jira";
+        trello: "trello";
+        confluence: "confluence";
+        asana: "asana";
+    }>;
+    adapter_id: z.ZodString;
+    label: z.ZodString;
+    status: z.ZodDefault<z.ZodEnum<{
+        experimental: "experimental";
+        disabled: "disabled";
+        active: "active";
+    }>>;
+    auth: z.ZodObject<{
+        mode: z.ZodEnum<{
+            none: "none";
+            pat: "pat";
+            oauth: "oauth";
+            "managed-identity": "managed-identity";
+            "app-installation": "app-installation";
+        }>;
+        required_env: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        secret_fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    capabilities: z.ZodArray<z.ZodObject<{
+        operation: z.ZodEnum<{
+            link: "link";
+            update: "update";
+            create: "create";
+            query: "query";
+        }>;
+        entity_kinds: z.ZodArray<z.ZodEnum<{
+            epic: "epic";
+            feature: "feature";
+            insight: "insight";
+            debate: "debate";
+            task: "task";
+        }>>;
+        dry_run: z.ZodDefault<z.ZodBoolean>;
+        apply: z.ZodDefault<z.ZodBoolean>;
+        idempotent: z.ZodDefault<z.ZodBoolean>;
+        required_fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    mapping: z.ZodObject<{
+        external_project_field: z.ZodOptional<z.ZodString>;
+        external_id_field: z.ZodString;
+        external_url_field: z.ZodOptional<z.ZodString>;
+        canonical_ref_field: z.ZodString;
+        parent_ref_field: z.ZodOptional<z.ZodString>;
+        entity_type_field: z.ZodString;
+        title_field: z.ZodString;
+        status_field: z.ZodString;
+    }, z.core.$strip>;
+    canonical_state_boundary: z.ZodObject<{
+        source_of_truth: z.ZodLiteral<"codesdd">;
+        state_paths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        external_state_authoritative: z.ZodLiteral<false>;
+        hidden_state_allowed: z.ZodLiteral<false>;
+    }, z.core.$strip>;
+    governance: z.ZodObject<{
+        owner: z.ZodString;
+        sync_requires_dry_run: z.ZodDefault<z.ZodBoolean>;
+        mutation_requires_approval: z.ZodDefault<z.ZodBoolean>;
+        audit_event: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const canonicalBacklogItemSchema: z.ZodObject<{
+    ref: z.ZodString;
+    kind: z.ZodEnum<{
+        epic: "epic";
+        feature: "feature";
+        insight: "insight";
+        debate: "debate";
+    }>;
+    title: z.ZodString;
+    status: z.ZodString;
+    parent_ref: z.ZodOptional<z.ZodString>;
+    labels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const backlogProjectionItemSchema: z.ZodObject<{
+    schema_version: z.ZodDefault<z.ZodLiteral<1>>;
+    provider: z.ZodEnum<{
+        generic: "generic";
+        "azure-devops": "azure-devops";
+        jira: "jira";
+        trello: "trello";
+        confluence: "confluence";
+        asana: "asana";
+    }>;
+    canonical_ref: z.ZodString;
+    entity_kind: z.ZodEnum<{
+        epic: "epic";
+        feature: "feature";
+        insight: "insight";
+        debate: "debate";
+        task: "task";
+    }>;
+    operation: z.ZodEnum<{
+        link: "link";
+        update: "update";
+        create: "create";
+        noop: "noop";
+    }>;
+    idempotency_key: z.ZodString;
+    external_type: z.ZodString;
+    fields: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    links: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        rel: z.ZodEnum<{
+            canonical: "canonical";
+            parent: "parent";
+            trace: "trace";
+        }>;
+        target_ref: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const backlogProjectionPlanSchema: z.ZodObject<{
+    schema_version: z.ZodDefault<z.ZodLiteral<1>>;
+    created_at: z.ZodString;
+    provider: z.ZodEnum<{
+        generic: "generic";
+        "azure-devops": "azure-devops";
+        jira: "jira";
+        trello: "trello";
+        confluence: "confluence";
+        asana: "asana";
+    }>;
+    mode: z.ZodEnum<{
+        apply: "apply";
+        "dry-run": "dry-run";
+    }>;
+    direction: z.ZodEnum<{
+        push: "push";
+        pull: "pull";
+        bidirectional: "bidirectional";
+    }>;
+    source_of_truth: z.ZodLiteral<"codesdd">;
+    items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        schema_version: z.ZodDefault<z.ZodLiteral<1>>;
+        provider: z.ZodEnum<{
+            generic: "generic";
+            "azure-devops": "azure-devops";
+            jira: "jira";
+            trello: "trello";
+            confluence: "confluence";
+            asana: "asana";
+        }>;
+        canonical_ref: z.ZodString;
+        entity_kind: z.ZodEnum<{
+            epic: "epic";
+            feature: "feature";
+            insight: "insight";
+            debate: "debate";
+            task: "task";
+        }>;
+        operation: z.ZodEnum<{
+            link: "link";
+            update: "update";
+            create: "create";
+            noop: "noop";
+        }>;
+        idempotency_key: z.ZodString;
+        external_type: z.ZodString;
+        fields: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        links: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            rel: z.ZodEnum<{
+                canonical: "canonical";
+                parent: "parent";
+                trace: "trace";
+            }>;
+            target_ref: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    warnings: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type BacklogProviderId = z.infer<typeof backlogProviderIdSchema>;
+export type BacklogEntityKind = z.infer<typeof backlogEntityKindSchema>;
+export type BacklogProviderCapability = z.infer<typeof backlogProviderCapabilitySchema>;
+export type BacklogProviderContract = z.infer<typeof backlogProviderContractSchema>;
+export type BacklogProviderContractInput = z.input<typeof backlogProviderContractSchema>;
+export type CanonicalBacklogItem = z.infer<typeof canonicalBacklogItemSchema>;
+export type BacklogProjectionItem = z.infer<typeof backlogProjectionItemSchema>;
+export type BacklogProjectionPlan = z.infer<typeof backlogProjectionPlanSchema>;
+export declare function createBacklogProviderContract(input: BacklogProviderContractInput): BacklogProviderContract;
+export declare function buildBacklogProjectionItem(input: {
+    contract: BacklogProviderContractInput;
+    item: CanonicalBacklogItem;
+    external_type: string;
+    operation?: BacklogProjectionItem['operation'];
+}): BacklogProjectionItem;
+//# sourceMappingURL=backlog-provider-contract.d.ts.map