@ductape/cli 0.2.23 → 0.3.1

package/dist/commands/migration-portfolio.js

@@ -0,0 +1,223 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { printJson } from '../lib/output.js';
+import { validateMigrationSlice } from './migration-slice.js';
+import { readMigrationJson, writeMigrationJson } from '../lib/migration-artifact.js';
+function read(file) {
+    return readMigrationJson(file);
+}
+function digest(file) {
+    try {
+        return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+export function proposeMigrationPartitions(opts) {
+    const ledgerPath = path.resolve(opts.ledger);
+    const ledger = read(ledgerPath);
+    const maxBytes = opts.maxBytes ?? 128_000;
+    const maxTokens = opts.maxTokens ?? 32_000;
+    if (!Number.isInteger(maxBytes) || maxBytes <= 0 || !Number.isInteger(maxTokens) || maxTokens <= 0) {
+        throw new Error('Partition byte and token limits must be positive integers.');
+    }
+    const known = new Set(ledger.entries.map((entry) => entry.file));
+    const graph = new Map(ledger.entries.map((entry) => [
+        entry.file,
+        [
+            ...(entry.references ?? []).filter((reference) => !reference.external).map((reference) => reference.target),
+            ...(entry.follow_up_files ?? []),
+        ].filter((target) => known.has(target)),
+    ]));
+    let nextIndex = 0;
+    const stack = [];
+    const onStack = new Set();
+    const indices = new Map();
+    const low = new Map();
+    const components = [];
+    const visit = (node) => {
+        indices.set(node, nextIndex);
+        low.set(node, nextIndex++);
+        stack.push(node);
+        onStack.add(node);
+        for (const dependency of graph.get(node) ?? []) {
+            if (!indices.has(dependency)) {
+                visit(dependency);
+                low.set(node, Math.min(low.get(node), low.get(dependency)));
+            }
+            else if (onStack.has(dependency)) {
+                low.set(node, Math.min(low.get(node), indices.get(dependency)));
+            }
+        }
+        if (low.get(node) === indices.get(node)) {
+            const component = [];
+            let current;
+            do {
+                current = stack.pop();
+                onStack.delete(current);
+                component.push(current);
+            } while (current !== node);
+            components.push(component.sort());
+        }
+    };
+    for (const entry of ledger.entries)
+        if (!indices.has(entry.file))
+            visit(entry.file);
+    const componentFor = new Map();
+    components.forEach((files, component) => files.forEach((file) => componentFor.set(file, component)));
+    const componentDependencies = components.map(() => new Set());
+    for (const [file, dependencies] of graph) {
+        const owner = componentFor.get(file);
+        for (const dependencyFile of dependencies) {
+            const dependency = componentFor.get(dependencyFile);
+            if (owner !== dependency)
+                componentDependencies[owner].add(dependency);
+        }
+    }
+    const ordered = [];
+    const seen = new Set();
+    const add = (component) => {
+        if (seen.has(component))
+            return;
+        seen.add(component);
+        componentDependencies[component].forEach(add);
+        ordered.push(component);
+    };
+    components.forEach((_, component) => add(component));
+    const tags = new Map(ordered.map((component, position) => [component, `partition-${position + 1}`]));
+    const partitions = ordered.map((component) => {
+        const files = components[component];
+        const byteEstimate = files.reduce((sum, file) => {
+            try {
+                return sum + fs.statSync(path.join(ledger.source, file)).size;
+            }
+            catch {
+                return sum;
+            }
+        }, 0);
+        const tokenEstimate = Math.ceil(byteEstimate / 4);
+        return {
+            tag: tags.get(component),
+            files,
+            dependencies: [...componentDependencies[component]].map((dependency) => tags.get(dependency)),
+            byte_estimate: byteEstimate,
+            token_estimate: tokenEstimate,
+            oversized_scc: byteEstimate > maxBytes || tokenEstimate > maxTokens,
+        };
+    });
+    const proposal = {
+        version: 1,
+        artifact_kind: 'ductape_migration_partition_proposal',
+        authority: 'advisory_only',
+        ledger: ledgerPath,
+        limits: { max_bytes: maxBytes, max_tokens: maxTokens, token_estimate: 'ceil(bytes/4)' },
+        partitions,
+    };
+    const output = path.resolve(opts.output ?? path.join(path.dirname(ledgerPath), 'partition-proposal.json'));
+    writeMigrationJson(output, proposal);
+    return { path: output, proposal };
+}
+export function initializeMigrationPortfolio(opts) {
+    const ledgerPath = path.resolve(opts.ledger);
+    const definition = read(path.resolve(opts.definition));
+    if (!Array.isArray(definition.partitions) || !Array.isArray(definition.slices) ||
+        !Array.isArray(definition.cross_slice_contracts)) {
+        throw new Error('Portfolio definition requires partitions, slices, and cross_slice_contracts arrays.');
+    }
+    const output = path.resolve(opts.output ?? path.join(path.dirname(ledgerPath), 'portfolio.json'));
+    if (fs.existsSync(output))
+        throw new Error(`Migration portfolio already exists: ${output}`);
+    const portfolio = {
+        version: 1,
+        artifact_kind: 'ductape_migration_portfolio',
+        ledger: ledgerPath,
+        ...definition,
+        partitions: definition.partitions.map((partition) => ({
+            ...partition,
+            provenance: partition.files.map((file) => ({
+                file,
+                checksum: digest(path.join(read(ledgerPath).source, file)) ?? '',
+            })),
+        })),
+        slices: definition.slices.map((slice) => path.resolve(slice)),
+    };
+    writeMigrationJson(output, portfolio, { createOnly: true });
+    return { path: output, portfolio };
+}
+export function validateMigrationPortfolio(portfolioPath) {
+    const resolved = path.resolve(portfolioPath);
+    const portfolio = read(resolved);
+    if (portfolio.artifact_kind !== 'ductape_migration_portfolio')
+        throw new Error('Invalid migration portfolio.');
+    const ledger = read(portfolio.ledger);
+    const blockers = [];
+    const coverage = new Map();
+    for (const partition of portfolio.partitions) {
+        if (!partition.tag || partition.context_budget <= 0 || !partition.summary.trim()) {
+            blockers.push(`partition ${partition.tag || '<unknown>'}: tag, positive context_budget, and summary are required`);
+        }
+        const provenance = new Map(partition.provenance.map((item) => [item.file, item.checksum]));
+        for (const file of partition.files) {
+            coverage.set(file, (coverage.get(file) ?? 0) + 1);
+            const recorded = provenance.get(file);
+            if (!recorded || digest(path.join(ledger.source, file)) !== recorded) {
+                blockers.push(`partition ${partition.tag}: stale or missing provenance for ${file}`);
+            }
+        }
+    }
+    for (const entry of ledger.entries) {
+        if (!coverage.has(entry.file))
+            blockers.push(`portfolio coverage missing: ${entry.file}`);
+    }
+    for (const [file, count] of coverage) {
+        if (!ledger.entries.some((entry) => entry.file === file))
+            blockers.push(`partition references unknown file: ${file}`);
+        if (count > 1)
+            blockers.push(`file appears in multiple partitions: ${file}`);
+    }
+    const sliceTags = new Set();
+    if (portfolio.slices.length === 0)
+        blockers.push('portfolio must contain at least one migration slice');
+    for (const slicePath of portfolio.slices) {
+        const result = validateMigrationSlice(slicePath);
+        sliceTags.add(result.tag);
+        if (!result.ready)
+            blockers.push(`slice ${result.tag}: ${result.blockers.join('; ')}`);
+    }
+    for (const contract of portfolio.cross_slice_contracts) {
+        if (!sliceTags.has(contract.provider) || !sliceTags.has(contract.consumer) ||
+            !contract.contract || !contract.evidence) {
+            blockers.push(`cross-slice contract ${contract.provider} -> ${contract.consumer} is incomplete`);
+        }
+    }
+    return {
+        portfolio: resolved,
+        ready: blockers.length === 0,
+        partitions: portfolio.partitions.length,
+        slices: portfolio.slices.length,
+        coverage: { reviewed_files: ledger.entries.length, partitioned_files: coverage.size },
+        blockers,
+    };
+}
+export function runMigrationPortfolioInit(opts) {
+    const result = initializeMigrationPortfolio(opts);
+    printJson({ path: result.path, partitions: result.portfolio.partitions.length }, Boolean(opts.json));
+}
+export function runMigrationPortfolioValidate(opts) {
+    const result = validateMigrationPortfolio(opts.portfolio);
+    printJson(result, Boolean(opts.json));
+    if (opts.strict && !result.ready) {
+        throw new Error('Migration portfolio is not ready: resolve every partition, slice, and contract blocker.');
+    }
+}
+export function runMigrationPortfolioPropose(opts) {
+    const result = proposeMigrationPartitions(opts);
+    printJson({
+        path: result.path,
+        authority: result.proposal.authority,
+        partitions: result.proposal.partitions.length,
+        oversized_sccs: result.proposal.partitions.filter((partition) => partition.oversized_scc).length,
+    }, Boolean(opts.json));
+}

package/dist/commands/migration-products.d.ts

@@ -0,0 +1,23 @@
+export declare function initializeProductMap(opts: {
+    analysis: string;
+    definition: string;
+    output: string;
+}): {
+    path: string;
+};
+export declare function validateProductMap(file: string): {
+    artifact: string;
+    ready: boolean;
+    blockers: string[];
+};
+export declare function runMigrationProductsInit(opts: {
+    analysis: string;
+    definition: string;
+    output: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationProductsValidate(opts: {
+    file: string;
+    strict?: boolean;
+    json?: boolean;
+}): void;

package/dist/commands/migration-products.js

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { printJson } from '../lib/output.js';
+import { readMigrationJson, writeMigrationJson } from '../lib/migration-artifact.js';
+function read(file) {
+    return readMigrationJson(file);
+}
+export function initializeProductMap(opts) {
+    const analysisPath = path.resolve(opts.analysis);
+    const definition = read(opts.definition);
+    if (!Array.isArray(definition.mappings) || !Array.isArray(definition.assets) ||
+        !Array.isArray(definition.promotions)) {
+        throw new Error('Definition requires mappings, assets, and promotions arrays.');
+    }
+    const artifact = {
+        version: 1,
+        artifact_kind: 'ductape_service_product_map',
+        analysis: analysisPath,
+        ...definition,
+    };
+    const output = path.resolve(opts.output);
+    if (fs.existsSync(output))
+        throw new Error(`Service-to-product map already exists: ${output}`);
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    writeMigrationJson(output, artifact, { createOnly: true });
+    return { path: output };
+}
+export function validateProductMap(file) {
+    const resolved = path.resolve(file);
+    const artifact = read(resolved);
+    if (artifact.artifact_kind !== 'ductape_service_product_map')
+        throw new Error('Invalid service-to-product map.');
+    const analysis = read(artifact.analysis);
+    const blockers = [];
+    const assignment = new Map();
+    for (const mapping of artifact.mappings) {
+        if (!mapping.service || !mapping.product_tag || !mapping.environments.length || !mapping.evidence) {
+            blockers.push(`mapping ${mapping.service || '<unknown>'}: service, product, environments, and evidence are required`);
+        }
+        for (const manifest of mapping.manifests) {
+            assignment.set(manifest, [...(assignment.get(manifest) ?? []), mapping.service]);
+        }
+    }
+    for (const unit of analysis.workspace_units ?? []) {
+        const owners = assignment.get(unit.manifest) ?? [];
+        if (owners.length === 0)
+            blockers.push(`workspace unit is unmapped: ${unit.manifest}`);
+        if (owners.length > 1)
+            blockers.push(`workspace unit has multiple service owners: ${unit.manifest}`);
+    }
+    for (const manifest of assignment.keys()) {
+        if (!(analysis.workspace_units ?? []).some((unit) => unit.manifest === manifest)) {
+            blockers.push(`mapping references unknown workspace unit: ${manifest}`);
+        }
+    }
+    for (const asset of artifact.assets) {
+        if (!asset.kind || !asset.tag || !asset.product_tag || !asset.inventory_evidence) {
+            blockers.push(`asset ${asset.tag || '<unknown>'}: identity and inventory evidence are required`);
+        }
+        for (const environment of asset.required_environments) {
+            if (!asset.configured_environments.includes(environment)) {
+                blockers.push(`asset ${asset.kind}:${asset.tag} missing environment configuration: ${environment}`);
+            }
+        }
+    }
+    for (const promotion of artifact.promotions) {
+        if (!promotion.product_tag || !promotion.from || !promotion.to ||
+            !promotion.entry_conditions.length || !promotion.validation.length || !promotion.rollback.length) {
+            blockers.push(`promotion ${promotion.from || '?'} -> ${promotion.to || '?'} is incomplete`);
+        }
+    }
+    const mappedProducts = new Set(artifact.mappings.map((mapping) => mapping.product_tag));
+    for (const product of mappedProducts) {
+        if (!artifact.promotions.some((promotion) => promotion.product_tag === product)) {
+            blockers.push(`product has no promotion plan: ${product}`);
+        }
+    }
+    return { artifact: resolved, ready: blockers.length === 0, blockers };
+}
+export function runMigrationProductsInit(opts) {
+    printJson(initializeProductMap(opts), Boolean(opts.json));
+}
+export function runMigrationProductsValidate(opts) {
+    const result = validateProductMap(opts.file);
+    printJson(result, Boolean(opts.json));
+    if (opts.strict && !result.ready)
+        throw new Error('Service-to-product mapping is not ready.');
+}

package/dist/commands/migration-review.d.ts

@@ -0,0 +1,248 @@
+type ReviewStatus = 'pending' | 'reviewed' | 'excluded';
+type ParityStatus = 'pending' | 'verified' | 'not_applicable';
+type ReferenceKind = 'import' | 'caller' | 'callee' | 'implements' | 'event' | 'test' | 'config' | 'schema';
+interface ParityEvidence {
+    status: ParityStatus;
+    evidence: string[];
+    reason?: string;
+}
+interface ReviewEntry {
+    file: string;
+    status: ReviewStatus;
+    safety: 'names_only' | 'normal';
+    baseline_checksum: string | null;
+    reviewed_checksum: string | null;
+    purpose: string;
+    dependencies: string[];
+    follow_up_files: string[];
+    references: Array<{
+        kind: ReferenceKind;
+        target: string;
+        external: boolean;
+        evidence: string;
+    }>;
+    interfaces: string[];
+    findings: Array<{
+        kind: string;
+        evidence: string;
+        location: {
+            start_line: number;
+            end_line: number;
+        };
+        symbol: {
+            kind: 'module' | 'class' | 'interface' | 'function' | 'method' | 'field' | 'route' | 'event' | 'schema' | 'other';
+            name: string;
+            qualified_name?: string;
+        };
+        classification: 'observed' | 'inferred' | 'proposed' | 'confirmed';
+        confidence: 'low' | 'medium' | 'high';
+        requires_followup: string[];
+    }>;
+    exclusion_reason?: string;
+    exclusion?: {
+        classification: 'generated' | 'vendor' | 'build' | 'snapshot' | 'other';
+        reason: string;
+        owner?: string;
+        generator?: string;
+        regeneration_test?: string;
+    };
+    interface_parity: ParityEvidence;
+    functional_parity: ParityEvidence;
+    operational_parity: ParityEvidence;
+}
+interface ReviewLedger {
+    version: 1;
+    artifact_kind: 'ai_migration_review_ledger';
+    source: string;
+    created_at: string;
+    revision: number;
+    events: Array<{
+        revision: number;
+        timestamp: string;
+        actor: string;
+        tool: '@ductape/cli';
+        tool_version: string;
+        operation: string;
+        state_hash: string;
+        previous_hash: string | null;
+        hash: string;
+    }>;
+    entries: ReviewEntry[];
+}
+interface LedgerSignature {
+    version: 1;
+    artifact_kind: 'ductape_review_ledger_signature';
+    ledger: string;
+    ledger_checksum: string;
+    key_id: string;
+    algorithm: 'Ed25519';
+    signed_at: string;
+    signature: string;
+}
+export declare function initializeReviewLedger(analysisPath: string, ledgerPath?: string): {
+    ledger: ReviewLedger;
+    path: string;
+};
+export declare function validateReviewLedger(ledgerPath: string): {
+    ledger: string;
+    source: string;
+    ready: boolean;
+    coverage: {
+        total: number;
+        reviewed: number;
+        excluded: number;
+        pending: number;
+        percent: number;
+    };
+    blockers: {
+        pending: string[];
+        stale: string[];
+        invalid_exclusions: string[];
+        invalid_generated_exclusions: string[];
+        missing_follow_ups: {
+            file: string;
+            follow_up: string;
+        }[];
+        uncovered_references: {
+            file: string;
+            kind: ReferenceKind;
+            target: string;
+        }[];
+        missing_finding_provenance: {
+            file: string;
+            finding: number;
+        }[];
+        missing_symbol_provenance: {
+            file: string;
+            finding: number;
+        }[];
+        probable_moves: {
+            from: string;
+            candidates: string[];
+        }[];
+        invalidated_dependents: string[];
+        audit_errors: string[];
+        missing_context: string[];
+        incomplete_parity: {
+            file: string;
+            concern: string;
+        }[];
+    };
+};
+export declare function snapshotReviewedFile(ledgerPath: string, file: string): ReviewEntry;
+export declare function recordReviewContext(ledgerPath: string, file: string, dataPath: string): ReviewEntry;
+export declare function addFollowUpFile(ledgerPath: string, fromFile: string, followUpFile: string): ReviewEntry;
+export declare function excludeReviewFile(ledgerPath: string, file: string, exclusion: NonNullable<ReviewEntry['exclusion']>): ReviewEntry;
+export declare function setParityEvidence(ledgerPath: string, file: string, concern: 'interface' | 'functional' | 'operational', status: Exclude<ParityStatus, 'pending'>, evidence?: string, reason?: string): ReviewEntry;
+export declare function reopenReviewFile(ledgerPath: string, file: string): ReviewEntry;
+export declare function moveReviewedFile(ledgerPath: string, from: string, to: string): ReviewEntry;
+export declare function signReviewLedger(opts: {
+    ledger: string;
+    privateKey: string;
+    keyId: string;
+    output?: string;
+}): {
+    path: string;
+    signature: LedgerSignature;
+};
+export declare function verifyReviewLedgerSignature(opts: {
+    ledger: string;
+    signature: string;
+    publicKey: string;
+}): {
+    ledger: string;
+    key_id: string;
+    valid: boolean;
+};
+export declare function mergeReviewLedgers(opts: {
+    base: string;
+    current: string;
+    incoming: string;
+    output: string;
+}): {
+    merged: boolean;
+    conflicts: string[];
+    output: null;
+} | {
+    merged: boolean;
+    conflicts: never[];
+    output: string;
+};
+export declare function runMigrationReviewInit(opts: {
+    analysis: string;
+    output?: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationReviewValidate(opts: {
+    ledger: string;
+    strict?: boolean;
+    json?: boolean;
+}): void;
+export declare function runMigrationReviewSnapshot(opts: {
+    ledger: string;
+    file: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationReviewRecord(opts: {
+    ledger: string;
+    file: string;
+    data: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationReviewFollowUp(opts: {
+    ledger: string;
+    file: string;
+    followUp: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationReviewExclude(opts: {
+    ledger: string;
+    file: string;
+    classification: NonNullable<ReviewEntry['exclusion']>['classification'];
+    reason: string;
+    owner?: string;
+    generator?: string;
+    regenerationTest?: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationReviewParity(opts: {
+    ledger: string;
+    file: string;
+    concern: 'interface' | 'functional' | 'operational';
+    status: 'verified' | 'not_applicable';
+    evidence?: string;
+    reason?: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationReviewReopen(opts: {
+    ledger: string;
+    file: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationReviewMove(opts: {
+    ledger: string;
+    from: string;
+    to: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationReviewSign(opts: {
+    ledger: string;
+    privateKey: string;
+    keyId: string;
+    output?: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationReviewVerifySignature(opts: {
+    ledger: string;
+    signature: string;
+    publicKey: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationReviewMerge(opts: {
+    base: string;
+    current: string;
+    incoming: string;
+    output: string;
+    json?: boolean;
+}): void;
+export {};