mustflow 1.15.97

package/dist/cli/commands/verify.js

@@ -0,0 +1,448 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { runRun } from './run.js';
+import { createChangeVerificationReport, } from '../../core/change-verification.js';
+import { createVerificationPlan } from '../../core/verification-plan.js';
+import { readCommandContract } from '../../core/config-loading.js';
+import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { t } from '../lib/i18n.js';
+import { resolveMustflowRoot } from '../lib/project-root.js';
+const VERIFY_SCHEMA_VERSION = '1';
+function createBufferedOutput() {
+    const stdout = [];
+    const stderr = [];
+    return {
+        reporter: {
+            stdout(message) {
+                stdout.push(`${message}\n`);
+            },
+            stderr(message) {
+                stderr.push(`${message}\n`);
+            },
+        },
+        stdout() {
+            return stdout.join('');
+        },
+        stderr() {
+            return stderr.join('');
+        },
+    };
+}
+export function getVerifyHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf verify --reason <event> [options] | mf verify --from-plan <path> [options]',
+        summary: t(lang, 'verify.help.summary'),
+        options: [
+            { label: '--reason <event>', description: t(lang, 'verify.help.option.reason') },
+            { label: '--from-plan <path>', description: t(lang, 'verify.help.option.fromPlan') },
+            { label: '--plan-only', description: t(lang, 'verify.help.option.planOnly') },
+            { label: '--json', description: t(lang, 'cli.option.json') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: [
+            'mf verify --reason code_change',
+            'mf verify --reason docs_change --json',
+            'mf verify --reason docs_change --plan-only --json',
+            'mf verify --from-plan verify-plan.json --json',
+            'mf verify --reason mustflow_docs_change',
+        ],
+        exitCodes: [
+            { label: '0', description: t(lang, 'verify.help.exit.ok') },
+            { label: '1', description: t(lang, 'verify.help.exit.fail') },
+        ],
+    }, lang);
+}
+function parseVerifyArgs(args) {
+    let reason;
+    let fromPlan;
+    let json = false;
+    let planOnly = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--json') {
+            json = true;
+            continue;
+        }
+        if (arg === '--plan-only') {
+            planOnly = true;
+            continue;
+        }
+        if (arg === '--reason') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('-')) {
+                return { json, planOnly, reason, error: 'missing_reason_value' };
+            }
+            reason = value;
+            index += 1;
+            continue;
+        }
+        if (arg === '--from-plan') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('-')) {
+                return { json, planOnly, reason, fromPlan, error: 'missing_from_plan_value' };
+            }
+            fromPlan = value;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--reason=')) {
+            const value = arg.slice('--reason='.length);
+            if (value.length === 0) {
+                return { json, planOnly, reason, error: 'missing_reason_value' };
+            }
+            reason = value;
+            continue;
+        }
+        if (arg.startsWith('--from-plan=')) {
+            const value = arg.slice('--from-plan='.length);
+            if (value.length === 0) {
+                return { json, planOnly, reason, fromPlan, error: 'missing_from_plan_value' };
+            }
+            fromPlan = value;
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            return { json, planOnly, reason, error: arg };
+        }
+        return { json, planOnly, reason, error: `unexpected:${arg}` };
+    }
+    return { json, planOnly, reason, fromPlan };
+}
+function uniqueStrings(values) {
+    return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))];
+}
+function readStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === 'string');
+}
+function readNumber(value) {
+    return Number.isInteger(value) && Number(value) >= 0 ? Number(value) : null;
+}
+function readUpdatePolicies(value) {
+    return readStringArray(value).filter((item) => item === 'update' || item === 'update_or_mark_stale' || item === 'not_applicable');
+}
+function readChangeSource(value) {
+    return value === 'changed' || value === 'paths' ? value : 'paths';
+}
+function emptyClassificationSummary(validationReasons) {
+    return {
+        fileCount: 0,
+        publicSurfaceCount: 0,
+        changeKinds: [],
+        validationReasons,
+        updatePolicies: [],
+        driftChecks: [],
+        affectedContracts: [],
+    };
+}
+function readClassificationSummary(value, fallbackReasons) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return emptyClassificationSummary(fallbackReasons);
+    }
+    const record = value;
+    const validationReasons = uniqueStrings([...fallbackReasons, ...readStringArray(record.validationReasons)]);
+    return {
+        fileCount: readNumber(record.fileCount) ?? 0,
+        publicSurfaceCount: readNumber(record.publicSurfaceCount) ?? 0,
+        changeKinds: readStringArray(record.changeKinds),
+        validationReasons,
+        updatePolicies: readUpdatePolicies(record.updatePolicies),
+        driftChecks: readStringArray(record.driftChecks),
+        affectedContracts: readStringArray(record.affectedContracts),
+    };
+}
+function readClassifications(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            return false;
+        }
+        const record = item;
+        const surface = record.surface;
+        const surfaceRecord = surface;
+        return (typeof record.path === 'string' &&
+            Array.isArray(record.changeKinds) &&
+            readStringArray(record.changeKinds).length === record.changeKinds.length &&
+            surface !== null &&
+            typeof surface === 'object' &&
+            !Array.isArray(surface) &&
+            typeof surfaceRecord.kind === 'string' &&
+            typeof surfaceRecord.category === 'string' &&
+            typeof surfaceRecord.isPublicSurface === 'boolean' &&
+            Array.isArray(surfaceRecord.validationReasons) &&
+            readStringArray(surfaceRecord.validationReasons).length === surfaceRecord.validationReasons.length &&
+            Array.isArray(surfaceRecord.affectedContracts) &&
+            readStringArray(surfaceRecord.affectedContracts).length === surfaceRecord.affectedContracts.length &&
+            readUpdatePolicies([surfaceRecord.updatePolicy]).length === 1 &&
+            Array.isArray(surfaceRecord.driftChecks) &&
+            readStringArray(surfaceRecord.driftChecks).length === surfaceRecord.driftChecks.length);
+    });
+}
+function createSyntheticClassificationReport(reasons, source = 'paths', files = []) {
+    return {
+        source,
+        files,
+        classifications: [],
+        summary: emptyClassificationSummary(reasons),
+    };
+}
+function readClassificationReport(plan, fallbackReasons) {
+    if (!plan || typeof plan !== 'object' || Array.isArray(plan)) {
+        return createSyntheticClassificationReport(fallbackReasons);
+    }
+    const record = plan;
+    const summary = readClassificationSummary(record.classification_summary ?? record.summary, fallbackReasons);
+    const files = readStringArray(record.files);
+    const classifications = readClassifications(record.classifications);
+    return {
+        source: readChangeSource(record.source),
+        files,
+        classifications,
+        summary,
+    };
+}
+function readPlanReasons(plan) {
+    if (!plan || typeof plan !== 'object' || Array.isArray(plan)) {
+        return [];
+    }
+    const record = plan;
+    const summary = record.summary;
+    const classificationSummary = record.classification_summary;
+    const verification = record.verification;
+    const reasons = [
+        typeof record.reason === 'string' ? record.reason : '',
+        ...readStringArray(record.reasons),
+        ...readStringArray(record.validationReasons),
+        ...(summary && typeof summary === 'object' && !Array.isArray(summary)
+            ? readStringArray(summary.validationReasons)
+            : []),
+        ...(classificationSummary && typeof classificationSummary === 'object' && !Array.isArray(classificationSummary)
+            ? readStringArray(classificationSummary.validationReasons)
+            : []),
+        ...(verification && typeof verification === 'object' && !Array.isArray(verification)
+            ? readStringArray(verification.reasons)
+            : []),
+    ];
+    return uniqueStrings(reasons);
+}
+function resolvePlanPath(projectRoot, inputPath) {
+    const resolved = path.resolve(projectRoot, inputPath);
+    const relative = path.relative(projectRoot, resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error('plan_path_outside_root');
+    }
+    return resolved;
+}
+function readInputFromPlan(projectRoot, inputPath) {
+    let parsed;
+    const planPath = resolvePlanPath(projectRoot, inputPath);
+    try {
+        parsed = JSON.parse(readFileSync(planPath, 'utf8'));
+    }
+    catch {
+        throw new Error('invalid_plan_file');
+    }
+    const reasons = readPlanReasons(parsed);
+    if (reasons.length === 0) {
+        throw new Error('missing_plan_reasons');
+    }
+    return {
+        reasons,
+        classificationReport: readClassificationReport(parsed, reasons),
+    };
+}
+function planErrorMessageKey(code) {
+    switch (code) {
+        case 'plan_path_outside_root':
+            return 'verify.error.plan_path_outside_root';
+        case 'missing_plan_reasons':
+            return 'verify.error.missing_plan_reasons';
+        default:
+            return 'verify.error.invalid_plan_file';
+    }
+}
+function skippedResult(candidate) {
+    return {
+        intent: candidate.intent || null,
+        status: 'skipped',
+        skipped: true,
+        reason: candidate.reason,
+        detail: candidate.detail,
+        exit_code: null,
+        receipt: null,
+    };
+}
+function runVerificationIntent(intent, lang) {
+    const output = createBufferedOutput();
+    const exitCode = runRun([intent, '--json'], output.reporter, lang);
+    const rawStdout = output.stdout().trim();
+    let receipt = null;
+    let status = exitCode === 0 ? 'passed' : 'failed';
+    try {
+        const parsed = JSON.parse(rawStdout);
+        receipt = parsed;
+        const receiptStatus = parsed.status;
+        if (receiptStatus === 'passed' ||
+            receiptStatus === 'failed' ||
+            receiptStatus === 'timed_out' ||
+            receiptStatus === 'start_failed') {
+            status = receiptStatus;
+        }
+    }
+    catch {
+        status = 'failed';
+    }
+    return {
+        intent,
+        status,
+        skipped: false,
+        reason: exitCode === 0 ? null : 'run_failed',
+        detail: output.stderr().trim() || null,
+        exit_code: exitCode,
+        receipt,
+    };
+}
+function summarizeResults(results) {
+    const ran = results.filter((result) => !result.skipped).length;
+    const passed = results.filter((result) => result.status === 'passed').length;
+    const skipped = results.filter((result) => result.skipped).length;
+    const failed = results.filter((result) => !result.skipped &&
+        (result.status === 'failed' || result.status === 'timed_out' || result.status === 'start_failed')).length;
+    return {
+        matched: results.filter((result) => result.intent !== null).length,
+        ran,
+        passed,
+        failed,
+        skipped,
+    };
+}
+function getVerificationStatus(summary) {
+    if (summary.failed > 0) {
+        return 'failed';
+    }
+    if (summary.ran === 0) {
+        return 'blocked';
+    }
+    if (summary.skipped > 0) {
+        return 'partial';
+    }
+    return 'passed';
+}
+function createVerifyOutput(reasons, planSource, projectRoot, lang) {
+    const contract = readCommandContract(projectRoot);
+    const candidatesByIntent = new Map();
+    const unmatchedCandidates = [];
+    for (const reason of reasons) {
+        const plan = createVerificationPlan(contract, reason);
+        for (const candidate of plan.candidates) {
+            if (!candidate.intent) {
+                unmatchedCandidates.push(candidate);
+                continue;
+            }
+            if (!candidatesByIntent.has(candidate.intent)) {
+                candidatesByIntent.set(candidate.intent, candidate);
+            }
+        }
+    }
+    const candidates = [...candidatesByIntent.values(), ...unmatchedCandidates].sort((left, right) => left.intent.localeCompare(right.intent));
+    const results = candidates.map((candidate) => candidate.status === 'runnable' ? runVerificationIntent(candidate.intent, lang) : skippedResult(candidate));
+    const summary = summarizeResults(results);
+    return {
+        schema_version: VERIFY_SCHEMA_VERSION,
+        command: 'verify',
+        mustflow_root: projectRoot,
+        reason: reasons.join(', '),
+        reasons,
+        plan_source: planSource,
+        status: getVerificationStatus(summary),
+        summary,
+        results,
+    };
+}
+function createPlanOnlyOutput(input, projectRoot) {
+    const contract = readCommandContract(projectRoot);
+    return createChangeVerificationReport(input.classificationReport, contract, projectRoot);
+}
+function renderVerifyOutput(output, lang) {
+    const lines = [
+        t(lang, 'verify.title'),
+        `${t(lang, 'label.mustflowRoot')}: ${output.mustflow_root}`,
+        `${t(lang, 'verify.label.reason')}: ${output.reason}`,
+        `${t(lang, 'verify.label.planSource')}: ${output.plan_source ?? t(lang, 'value.none')}`,
+        `${t(lang, 'verify.label.status')}: ${output.status}`,
+        `matched: ${output.summary.matched}`,
+        `ran: ${output.summary.ran}`,
+        `passed: ${output.summary.passed}`,
+        `failed: ${output.summary.failed}`,
+        `skipped: ${output.summary.skipped}`,
+        '',
+        t(lang, 'verify.label.results'),
+    ];
+    for (const result of output.results) {
+        const intent = result.intent ?? t(lang, 'value.none');
+        const reason = result.reason ? ` (${result.reason})` : '';
+        lines.push(`- ${intent}: ${result.status}${reason}`);
+    }
+    return lines.join('\n');
+}
+export function runVerify(args, reporter, lang = 'en') {
+    if (args.includes('--help') || args.includes('-h')) {
+        reporter.stdout(getVerifyHelp(lang));
+        return 0;
+    }
+    const parsed = parseVerifyArgs(args);
+    if (parsed.error) {
+        const message = parsed.error === 'missing_reason_value'
+            ? t(lang, 'cli.error.missingValue', { option: '--reason' })
+            : parsed.error === 'missing_from_plan_value'
+                ? t(lang, 'cli.error.missingValue', { option: '--from-plan' })
+                : parsed.error.startsWith('unexpected:')
+                    ? t(lang, 'cli.error.unexpectedArgument', { argument: parsed.error.slice('unexpected:'.length) })
+                    : t(lang, 'cli.error.unknownOption', { option: parsed.error });
+        printUsageError(reporter, message, 'mf verify --help', getVerifyHelp(lang), lang);
+        return 1;
+    }
+    if (parsed.reason && parsed.fromPlan) {
+        printUsageError(reporter, t(lang, 'verify.error.conflictingInputs'), 'mf verify --help', getVerifyHelp(lang), lang);
+        return 1;
+    }
+    if (!parsed.reason && !parsed.fromPlan) {
+        printUsageError(reporter, t(lang, 'verify.error.missingReason'), 'mf verify --help', getVerifyHelp(lang), lang);
+        return 1;
+    }
+    if (parsed.planOnly && !parsed.json) {
+        printUsageError(reporter, t(lang, 'verify.error.planOnlyJson'), 'mf verify --help', getVerifyHelp(lang), lang);
+        return 1;
+    }
+    const projectRoot = resolveMustflowRoot();
+    let input;
+    try {
+        input = parsed.fromPlan
+            ? readInputFromPlan(projectRoot, parsed.fromPlan)
+            : {
+                reasons: [parsed.reason],
+                classificationReport: createSyntheticClassificationReport([parsed.reason]),
+            };
+    }
+    catch (error) {
+        const code = error instanceof Error ? error.message : 'invalid_plan_file';
+        printUsageError(reporter, t(lang, planErrorMessageKey(code)), 'mf verify --help', getVerifyHelp(lang), lang);
+        return 1;
+    }
+    if (parsed.planOnly) {
+        reporter.stdout(JSON.stringify(createPlanOnlyOutput(input, projectRoot), null, 2));
+        return 0;
+    }
+    const output = createVerifyOutput(input.reasons, parsed.fromPlan ?? null, projectRoot, lang);
+    if (parsed.json) {
+        reporter.stdout(JSON.stringify(output, null, 2));
+    }
+    else {
+        reporter.stdout(renderVerifyOutput(output, lang));
+    }
+    return output.status === 'passed' ? 0 : 1;
+}

package/dist/cli/commands/version-sources.js

@@ -0,0 +1,79 @@
+import path from 'node:path';
+import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { isRecord } from '../lib/command-contract.js';
+import { t } from '../lib/i18n.js';
+import { resolveMustflowRoot } from '../lib/project-root.js';
+import { readTomlFile } from '../lib/toml.js';
+import { detectVersionSources, releaseVersioningIsEnabled, } from '../../core/version-sources.js';
+const VERSION_SOURCES_SCHEMA_VERSION = '1';
+export function getVersionSourcesHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf version-sources [options]',
+        summary: t(lang, 'versionSources.help.summary'),
+        options: [
+            { label: '--json', description: t(lang, 'cli.option.json') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: ['mf version-sources', 'mf version-sources --json'],
+        exitCodes: [
+            { label: '0', description: t(lang, 'versionSources.help.exit.ok') },
+            { label: '1', description: t(lang, 'cli.common.invalidInput') },
+        ],
+    }, lang);
+}
+function readPreferences(projectRoot) {
+    try {
+        const preferences = readTomlFile(path.join(projectRoot, '.mustflow', 'config', 'preferences.toml'));
+        return isRecord(preferences) ? preferences : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function getVersionSourcesOutput(projectRoot) {
+    const preferences = readPreferences(projectRoot);
+    return {
+        schema_version: VERSION_SOURCES_SCHEMA_VERSION,
+        command: 'version-sources',
+        mustflow_root: projectRoot,
+        versioning_enabled: releaseVersioningIsEnabled(preferences),
+        sources: detectVersionSources(projectRoot),
+    };
+}
+function renderVersionSources(output, lang) {
+    const lines = [
+        t(lang, 'versionSources.title'),
+        `${t(lang, 'label.mustflowRoot')}: ${output.mustflow_root}`,
+        `${t(lang, 'versionSources.label.versioning')}: ${output.versioning_enabled ? t(lang, 'versionSources.value.enabled') : t(lang, 'versionSources.value.disabled')}`,
+        '',
+        t(lang, 'versionSources.label.sources'),
+    ];
+    if (output.sources.length === 0) {
+        lines.push(`- ${t(lang, 'versionSources.noSources')}`);
+        return lines.join('\n');
+    }
+    for (const source of output.sources) {
+        const metadata = [source.kind, source.declared ? 'declared' : undefined, source.authority].filter(Boolean).join(', ');
+        lines.push(`- ${source.path} (${metadata})`);
+    }
+    return lines.join('\n');
+}
+export function runVersionSources(args, reporter, lang = 'en') {
+    if (args.includes('--help') || args.includes('-h')) {
+        reporter.stdout(getVersionSourcesHelp(lang));
+        return 0;
+    }
+    const supported = new Set(['--json']);
+    const unsupported = args.filter((arg) => !supported.has(arg));
+    if (unsupported.length > 0) {
+        printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: unsupported[0] }), 'mf version-sources --help', getVersionSourcesHelp(lang), lang);
+        return 1;
+    }
+    const output = getVersionSourcesOutput(resolveMustflowRoot());
+    if (args.includes('--json')) {
+        reporter.stdout(JSON.stringify(output, null, 2));
+        return 0;
+    }
+    reporter.stdout(renderVersionSources(output, lang));
+    return 0;
+}

package/dist/cli/commands/version.js

@@ -0,0 +1,57 @@
+import { printUsageError, renderCliError, renderHelp } from '../lib/cli-output.js';
+import { t } from '../lib/i18n.js';
+import { checkNpmLatestVersion } from '../lib/npm-version-check.js';
+import { readPackageMetadata } from '../lib/package-info.js';
+export function getVersionHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf version [options]',
+        summary: t(lang, 'version.help.summary'),
+        options: [
+            { label: '--check', description: t(lang, 'version.help.option.check') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: ['mf version', 'mf version --check'],
+        exitCodes: [
+            { label: '0', description: t(lang, 'version.help.exit.ok') },
+            { label: '1', description: t(lang, 'cli.common.invalidInput') },
+        ],
+    }, lang);
+}
+function renderVersionCheck(check, lang) {
+    const lines = [
+        `${check.packageName} ${check.currentVersion}`,
+        check.updateAvailable
+            ? t(lang, 'version.check.latestAvailable', { version: check.latestVersion })
+            : t(lang, 'version.check.upToDate', { version: check.latestVersion }),
+    ];
+    if (check.updateAvailable) {
+        lines.push('', t(lang, 'version.check.updateCommand'), check.updateCommand);
+    }
+    return lines.join('\n');
+}
+export async function runVersion(args, reporter, lang = 'en') {
+    if (args.includes('--help') || args.includes('-h')) {
+        reporter.stdout(getVersionHelp(lang));
+        return 0;
+    }
+    const supported = new Set(['--check']);
+    const unsupported = args.filter((arg) => !supported.has(arg));
+    if (unsupported.length > 0) {
+        printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: unsupported[0] }), 'mf version --help', getVersionHelp(lang), lang);
+        return 1;
+    }
+    const metadata = readPackageMetadata();
+    if (!args.includes('--check')) {
+        reporter.stdout(metadata.version);
+        return 0;
+    }
+    try {
+        reporter.stdout(renderVersionCheck(await checkNpmLatestVersion(metadata), lang));
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        reporter.stderr(renderCliError(t(lang, 'version.error.checkFailed', { message }), 'mf version --help', lang));
+        return 1;
+    }
+}