@tiangong-lca/cli 0.0.1

package/dist/src/lib/review-flow.js

@@ -0,0 +1,1110 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { writeJsonArtifact, writeJsonLinesArtifact, writeTextArtifact } from './artifacts.js';
+import { CliError } from './errors.js';
+import { coerceText, deepGet, extractFlowRecord, flowDatasetFromRow, isRecord, listify, loadRowsFromFile, normalizeText, } from './flow-governance.js';
+import { invokeLlm, readLlmRuntimeEnv } from './llm.js';
+const UUID_RE = /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/u;
+function walkStrings(node) {
+    if (typeof node === 'string') {
+        return node.trim() ? [node.trim()] : [];
+    }
+    if (Array.isArray(node)) {
+        return node.flatMap((item) => walkStrings(item));
+    }
+    if (!isRecord(node)) {
+        return [];
+    }
+    const strings = [];
+    if (typeof node['#text'] === 'string' && String(node['#text']).trim()) {
+        strings.push(String(node['#text']).trim());
+    }
+    Object.values(node).forEach((value) => {
+        strings.push(...walkStrings(value));
+    });
+    return strings;
+}
+function langTextForLang(value, lang) {
+    for (const item of listify(value)) {
+        if (!isRecord(item)) {
+            continue;
+        }
+        if (coerceText(item['@xml:lang']).toLowerCase() !== lang.toLowerCase()) {
+            continue;
+        }
+        const text = coerceText(item['#text']);
+        if (text) {
+            return text;
+        }
+    }
+    for (const item of listify(value)) {
+        const text = coerceText(item);
+        if (text) {
+            return text;
+        }
+    }
+    return '';
+}
+function findUuidInNode(node) {
+    if (isRecord(node)) {
+        for (const key of ['@refObjectId', '@uri']) {
+            const raw = coerceText(node[key]);
+            const match = raw.match(UUID_RE);
+            if (match) {
+                return match[0].toLowerCase();
+            }
+        }
+    }
+    const raw = coerceText(node);
+    const match = raw.match(UUID_RE);
+    return match ? match[0].toLowerCase() : '';
+}
+function flowRoot(doc) {
+    return isRecord(doc.flowDataSet) ? { ...doc.flowDataSet } : { ...doc };
+}
+function flowUuid(flow) {
+    return coerceText(deepGet(flow, ['flowInformation', 'dataSetInformation', 'common:UUID']));
+}
+function flowVersion(flow) {
+    return coerceText(deepGet(flow, [
+        'administrativeInformation',
+        'publicationAndOwnership',
+        'common:dataSetVersion',
+    ]));
+}
+function flowType(flow) {
+    return (coerceText(deepGet(flow, ['modellingAndValidation', 'LCIMethodAndAllocation', 'typeOfDataSet'])) || coerceText(deepGet(flow, ['modellingAndValidation', 'LCIMethod', 'typeOfDataSet'])));
+}
+function nameNode(flow) {
+    return deepGet(flow, ['flowInformation', 'dataSetInformation', 'name']);
+}
+function nameTexts(flow) {
+    return walkStrings(nameNode(flow));
+}
+function namePrimary(flow, lang) {
+    const name = nameNode(flow);
+    if (!isRecord(name)) {
+        return '';
+    }
+    return langTextForLang(name.baseName, lang);
+}
+function nameFingerprint(flow) {
+    const name = nameNode(flow);
+    if (!isRecord(name)) {
+        return '';
+    }
+    const parts = [];
+    for (const key of ['baseName', 'treatmentStandardsRoutes', 'mixAndLocationTypes']) {
+        const values = listify(name[key])
+            .map((item) => (isRecord(item) ? coerceText(item['#text']) : coerceText(item)))
+            .filter(Boolean);
+        if (values.length) {
+            parts.push(values.join(' | '));
+        }
+    }
+    const text = parts.length ? parts.join(' || ') : nameTexts(flow).join(' || ');
+    return normalizeText(text);
+}
+function classificationEntries(flow) {
+    return listify(deepGet(flow, [
+        'flowInformation',
+        'dataSetInformation',
+        'classificationInformation',
+        'common:classification',
+        'common:class',
+    ]))
+        .filter(isRecord)
+        .map((item) => ({
+        level: coerceText(item['@level']),
+        class_id: coerceText(item['@classId']),
+        text: coerceText(item['#text']),
+    }));
+}
+function elementaryClassEntries(flow) {
+    return listify(deepGet(flow, [
+        'flowInformation',
+        'dataSetInformation',
+        'classificationInformation',
+        'common:elementaryFlowCategorization',
+        'common:category',
+    ]))
+        .filter(isRecord)
+        .map((item) => ({
+        level: coerceText(item['@level']),
+        cat_id: coerceText(item['@catId']),
+        text: coerceText(item['#text']),
+    }));
+}
+function classificationLeaf(flow) {
+    const entries = classificationEntries(flow);
+    if (!entries.length) {
+        return {
+            class_id: '',
+            text: '',
+            key: '',
+        };
+    }
+    const leaf = entries[entries.length - 1];
+    const classId = leaf.class_id;
+    const key = `${classId}|${leaf.text}`.replace(/^\||\|$/gu, '');
+    return {
+        class_id: classId,
+        text: leaf.text,
+        key,
+    };
+}
+function flowProperties(flow) {
+    return listify(deepGet(flow, ['flowProperties', 'flowProperty'])).filter(isRecord);
+}
+function pickReferenceFlowProperty(flow) {
+    const props = flowProperties(flow);
+    for (const prop of props) {
+        const internalId = coerceText(prop['@dataSetInternalID']);
+        if (internalId === '0') {
+            return {
+                prop,
+                internalId,
+            };
+        }
+    }
+    if (props.length) {
+        return {
+            prop: props[0],
+            internalId: coerceText(props[0]['@dataSetInternalID']),
+        };
+    }
+    return {
+        prop: null,
+        internalId: '',
+    };
+}
+function quantitativeReferenceInternalId(flow) {
+    return coerceText(deepGet(flow, ['flowInformation', 'quantitativeReference', 'referenceToReferenceFlowProperty']));
+}
+function flowPropertyRef(prop) {
+    const ref = isRecord(prop.referenceToFlowPropertyDataSet)
+        ? prop.referenceToFlowPropertyDataSet
+        : null;
+    return {
+        uuid: findUuidInNode(ref),
+        version: coerceText(ref?.['@version']),
+        internal_id: coerceText(prop['@dataSetInternalID']),
+        short_name_en: langTextForLang(ref?.['common:shortDescription'], 'en'),
+    };
+}
+function computeSimilarity(left, right) {
+    if (!left || !right) {
+        return 0;
+    }
+    if (left === right) {
+        return 1;
+    }
+    const leftTokens = new Set(left.split(' ').filter(Boolean));
+    const rightTokens = new Set(right.split(' ').filter(Boolean));
+    if (!leftTokens.size || !rightTokens.size) {
+        return 0;
+    }
+    let intersection = 0;
+    leftTokens.forEach((token) => {
+        if (rightTokens.has(token)) {
+            intersection += 1;
+        }
+    });
+    return intersection / Math.max(leftTokens.size, rightTokens.size);
+}
+function createRuleFinding(flowUuidValue, baseVersion, severity, ruleId, message, options) {
+    return {
+        flow_uuid: flowUuidValue,
+        base_version: baseVersion,
+        severity,
+        rule_id: ruleId,
+        message,
+        fixability: options?.fixability ?? 'manual',
+        source: 'rule',
+        ...(options?.ruleSource ? { rule_source: options.ruleSource } : {}),
+        ...(options?.evidence ? { evidence: options.evidence } : {}),
+        ...(options?.action ? { action: options.action } : {}),
+    };
+}
+function applyMethodologyChecks(flow, flowUuidValue, baseVersion, ruleSource) {
+    const findings = [];
+    const allowedTypes = new Set(['elementary flow', 'product flow', 'waste flow']);
+    const typeOfDataset = flowType(flow).toLowerCase();
+    if (typeOfDataset && !allowedTypes.has(typeOfDataset)) {
+        findings.push(createRuleFinding(flowUuidValue, baseVersion, 'error', 'methodology_invalid_type_of_dataset', 'typeOfDataSet not in allowed set: Elementary flow | Product flow | Waste flow.', {
+            evidence: {
+                typeOfDataSet: flowType(flow),
+            },
+            ruleSource,
+        }));
+    }
+    const baseNameItems = listify(deepGet(flow, ['flowInformation', 'dataSetInformation', 'name', 'baseName']));
+    const baseNameEn = langTextForLang(baseNameItems, 'en');
+    if (!baseNameEn) {
+        findings.push(createRuleFinding(flowUuidValue, baseVersion, 'warning', 'methodology_missing_base_name_en', 'English baseName is missing (methodology marks English as mandatory).', {
+            fixability: 'auto',
+            ruleSource,
+        }));
+    }
+    if (baseNameItems.some((item) => {
+        const text = isRecord(item) ? coerceText(item['#text']) : coerceText(item);
+        return text.includes(';');
+    })) {
+        findings.push(createRuleFinding(flowUuidValue, baseVersion, 'warning', 'methodology_basename_semicolon', 'baseName contains semicolon; methodology requires comma-separated descriptors.', {
+            fixability: 'auto',
+            ruleSource,
+        }));
+    }
+    const quantId = quantitativeReferenceInternalId(flow);
+    const propertyIds = new Set(flowProperties(flow)
+        .map((prop) => coerceText(prop['@dataSetInternalID']))
+        .filter(Boolean));
+    if (quantId && !propertyIds.has(quantId)) {
+        findings.push(createRuleFinding(flowUuidValue, baseVersion, 'error', 'methodology_quant_ref_missing_target', 'referenceToReferenceFlowProperty points to a non-existing flowProperty internal ID.', {
+            evidence: {
+                referenceToReferenceFlowProperty: quantId,
+                available_internal_ids: [...propertyIds].sort(),
+            },
+            ruleSource,
+        }));
+    }
+    for (const [entries, label, idKey, maxLevel] of [
+        [classificationEntries(flow), 'product_classification', 'class_id', 4],
+        [elementaryClassEntries(flow), 'elementary_classification', 'cat_id', 2],
+    ]) {
+        const levels = [];
+        entries.forEach((entry) => {
+            const level = Number.parseInt(entry.level, 10);
+            if (Number.isInteger(level)) {
+                levels.push(level);
+            }
+            if (!coerceText(entry[idKey])) {
+                findings.push(createRuleFinding(flowUuidValue, baseVersion, 'warning', `methodology_missing_${idKey}`, `${label} entry has level but missing ${idKey}.`, {
+                    evidence: {
+                        entry,
+                    },
+                    ruleSource,
+                }));
+            }
+        });
+        if (levels.length) {
+            const uniqueLevels = [...new Set(levels)].sort((left, right) => left - right);
+            const expectedLevels = [];
+            for (let level = uniqueLevels[0]; level <= Math.min(maxLevel, uniqueLevels[uniqueLevels.length - 1]); level += 1) {
+                expectedLevels.push(level);
+            }
+            if (uniqueLevels[0] !== 0 ||
+                JSON.stringify(uniqueLevels) !== JSON.stringify(expectedLevels)) {
+                findings.push(createRuleFinding(flowUuidValue, baseVersion, 'warning', `methodology_${label}_level_gap`, `${label} levels should be continuous and start from 0.`, {
+                    evidence: {
+                        levels: uniqueLevels,
+                    },
+                    ruleSource,
+                }));
+            }
+        }
+    }
+    return findings;
+}
+function buildFlowSummaryAndRuleFindings(doc, methodologyRuleSource) {
+    const flow = flowRoot(doc);
+    const flowUuidValue = flowUuid(flow) || '(missing-uuid)';
+    const baseVersion = flowVersion(flow);
+    const typeOfDataset = flowType(flow);
+    const names = nameTexts(flow);
+    const leaf = classificationLeaf(flow);
+    const summary = {
+        flow_uuid: flowUuidValue,
+        base_version: baseVersion,
+        type_of_dataset: typeOfDataset,
+        names: {
+            primary_en: namePrimary(flow, 'en'),
+            primary_zh: namePrimary(flow, 'zh'),
+            all_texts: names.slice(0, 20),
+        },
+        classification: {
+            leaf,
+            path: classificationEntries(flow).slice(0, 20),
+        },
+        flow_property: {},
+        quantitative_reference: {
+            reference_flow_property_internal_id: quantitativeReferenceInternalId(flow),
+        },
+        unitgroup: {
+            uuid: '',
+            name: '',
+            reference_unit_name: '',
+            lookup_status: 'disabled',
+            lookup_source: '',
+        },
+        rule_signals: [],
+        similarity_candidates: [],
+        _name_fingerprint: nameFingerprint(flow),
+    };
+    const findings = [];
+    if (!typeOfDataset) {
+        findings.push(createRuleFinding(flowUuidValue, baseVersion, 'error', 'missing_type_of_dataset', 'typeOfDataSet is missing under modellingAndValidation.LCIMethod.'));
+    }
+    else if (typeOfDataset.toLowerCase() === 'elementary flow') {
+        findings.push(createRuleFinding(flowUuidValue, baseVersion, 'warning', 'elementary_flow_in_flow_review', 'Flow type is Elementary flow; check whether this batch should exclude it.', {
+            fixability: 'review-needed',
+            evidence: {
+                typeOfDataSet: typeOfDataset,
+            },
+        }));
+    }
+    if (!names.length) {
+        findings.push(createRuleFinding(flowUuidValue, baseVersion, 'warning', 'missing_name_text', 'No textual entries found under flowInformation.dataSetInformation.name.'));
+    }
+    else if (names.some((value) => value.toLowerCase().includes('emergy'))) {
+        findings.push(createRuleFinding(flowUuidValue, baseVersion, 'warning', 'name_contains_emergy', "Name subtree contains 'Emergy'.", {
+            fixability: 'review-needed',
+            evidence: {
+                matched_count: names.filter((value) => value.toLowerCase().includes('emergy')).length,
+            },
+        }));
+    }
+    if (!leaf.key) {
+        findings.push(createRuleFinding(flowUuidValue, baseVersion, 'warning', 'missing_classification_leaf', 'Classification leaf is missing.'));
+    }
+    const { prop, internalId } = pickReferenceFlowProperty(flow);
+    if (!prop) {
+        findings.push(createRuleFinding(flowUuidValue, baseVersion, 'error', 'missing_flow_property', 'No flowProperties.flowProperty entry found.'));
+    }
+    else {
+        const ref = flowPropertyRef(prop);
+        summary.flow_property = {
+            selected_internal_id: internalId || ref.internal_id,
+            referenced_uuid: ref.uuid,
+            referenced_version: ref.version,
+            referenced_short_name_en: ref.short_name_en,
+            available_count: flowProperties(flow).length,
+        };
+        if (!ref.uuid) {
+            findings.push(createRuleFinding(flowUuidValue, baseVersion, 'error', 'invalid_flow_property_reference', 'Could not parse flow property UUID from referenceToFlowPropertyDataSet.', {
+                evidence: {
+                    selected_internal_id: internalId || ref.internal_id,
+                },
+            }));
+        }
+        const quantId = summary.quantitative_reference.reference_flow_property_internal_id;
+        if (!quantId) {
+            findings.push(createRuleFinding(flowUuidValue, baseVersion, 'warning', 'missing_quantitative_reference', 'referenceToReferenceFlowProperty is missing.', {
+                fixability: 'auto',
+                evidence: {
+                    expected_internal_id: internalId || ref.internal_id,
+                },
+            }));
+        }
+        else if (internalId && quantId !== internalId) {
+            findings.push(createRuleFinding(flowUuidValue, baseVersion, 'warning', 'quantitative_reference_mismatch', 'Quantitative reference internal ID differs from selected reference flowProperty internal ID.', {
+                fixability: 'auto',
+                evidence: {
+                    quant_ref_internal_id: quantId,
+                    expected_internal_id: internalId,
+                },
+                action: 'Align quantitative reference internal ID to the selected flowProperty.',
+            }));
+        }
+    }
+    findings.push(...applyMethodologyChecks(flow, flowUuidValue, baseVersion, methodologyRuleSource));
+    summary.rule_signals = findings.slice(0, 20).map((finding) => ({
+        rule_id: coerceText(finding.rule_id),
+        severity: finding.severity,
+        message: coerceText(finding.message),
+        evidence: finding.evidence ?? {},
+    }));
+    return {
+        summary,
+        findings,
+    };
+}
+function buildSimilarity(summaries, threshold) {
+    const grouped = {};
+    const candidatesByFlow = {};
+    const pairs = [];
+    summaries.forEach((summary) => {
+        const leafKey = summary.classification.leaf.key;
+        const flowPropertyUuid = coerceText(summary.flow_property.referenced_uuid);
+        const unitgroupUuid = summary.unitgroup.uuid;
+        if (!leafKey || !summary._name_fingerprint) {
+            return;
+        }
+        const key = `${leafKey}::${flowPropertyUuid}::${unitgroupUuid}`;
+        grouped[key] ??= [];
+        grouped[key].push(summary);
+    });
+    Object.entries(grouped).forEach(([key, rows]) => {
+        if (rows.length < 2) {
+            return;
+        }
+        const [classificationGroup, flowPropertyUuid, unitgroupUuid] = key.split('::');
+        for (let leftIndex = 0; leftIndex < rows.length; leftIndex += 1) {
+            for (let rightIndex = leftIndex + 1; rightIndex < rows.length; rightIndex += 1) {
+                const left = rows[leftIndex];
+                const right = rows[rightIndex];
+                const similarity = computeSimilarity(left._name_fingerprint, right._name_fingerprint);
+                if (similarity < threshold) {
+                    continue;
+                }
+                const pair = {
+                    classification_group: classificationGroup,
+                    flow_property_uuid: flowPropertyUuid,
+                    unitgroup_uuid: unitgroupUuid,
+                    left_flow_uuid: left.flow_uuid,
+                    right_flow_uuid: right.flow_uuid,
+                    left_version: left.base_version,
+                    right_version: right.base_version,
+                    similarity: Number(similarity.toFixed(6)),
+                    left_name_en: left.names.primary_en,
+                    right_name_en: right.names.primary_en,
+                };
+                pairs.push(pair);
+                for (const [source, target] of [
+                    [left, right],
+                    [right, left],
+                ]) {
+                    candidatesByFlow[source.flow_uuid] ??= [];
+                    candidatesByFlow[source.flow_uuid].push({
+                        other_flow_uuid: target.flow_uuid,
+                        other_base_version: target.base_version,
+                        similarity: Number(similarity.toFixed(6)),
+                        other_name_en: target.names.primary_en,
+                        classification_group: classificationGroup,
+                    });
+                }
+            }
+        }
+    });
+    Object.keys(candidatesByFlow).forEach((flowUuidValue) => {
+        candidatesByFlow[flowUuidValue].sort((left, right) => right.similarity - left.similarity ||
+            left.other_flow_uuid.localeCompare(right.other_flow_uuid));
+        candidatesByFlow[flowUuidValue] = candidatesByFlow[flowUuidValue].slice(0, 5);
+    });
+    return {
+        pairs,
+        candidatesByFlow,
+    };
+}
+function parseLlmJsonOutput(output) {
+    const start = output.indexOf('{');
+    const end = output.lastIndexOf('}');
+    const candidate = start >= 0 && end > start ? output.slice(start, end + 1) : output;
+    try {
+        const parsed = JSON.parse(candidate);
+        return isRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function buildLlmPrompt(batch) {
+    return [
+        '请对以下 flow 摘要进行 LCI 复审，重点关注：',
+        '1) flow property 与 quantitative reference 是否合理/一致；',
+        '2) 同类别高相似度 flow 的重复/近重复风险；',
+        '3) 名称、分类、typeOfDataSet 的语义一致性与明显异常。',
+        '',
+        '规则：',
+        '- 只能依据输入摘要中的证据；',
+        '- 若证据不足，必须明确写证据不足；',
+        '- 对每条问题给出 flow_uuid；',
+        '- 输出必须是 JSON 对象。',
+        '',
+        '输出格式：{findings:[{flow_uuid, severity, fixability, evidence, action}]}。',
+        '',
+        `输入摘要:\n${JSON.stringify(batch, null, 2)}`,
+    ].join('\n');
+}
+function normalizeLlmFinding(item, summaryByUuid, fallbackFlowUuid = '') {
+    const flowUuidValue = coerceText(item.flow_uuid) || fallbackFlowUuid;
+    if (!flowUuidValue) {
+        return null;
+    }
+    const severity = (() => {
+        const value = coerceText(item.severity).toLowerCase();
+        if (value === 'error' || value === 'warning' || value === 'info') {
+            return value;
+        }
+        return 'warning';
+    })();
+    const evidence = item.evidence;
+    return {
+        flow_uuid: flowUuidValue,
+        base_version: summaryByUuid[flowUuidValue]?.base_version ?? '',
+        severity,
+        fixability: coerceText(item.fixability) || 'review-needed',
+        source: 'llm',
+        ...(isRecord(evidence)
+            ? { evidence }
+            : evidence === undefined
+                ? {}
+                : { evidence: { text: coerceText(evidence) } }),
+        ...(coerceText(item.action) || coerceText(item.suggestion) || coerceText(item.suggested_action)
+            ? {
+                action: coerceText(item.action) ||
+                    coerceText(item.suggestion) ||
+                    coerceText(item.suggested_action),
+            }
+            : {}),
+    };
+}
+async function runOptionalLlmReview(summaries, options) {
+    if (!options.enableLlm) {
+        return {
+            enabled: false,
+            reason: 'disabled',
+            batch_count: 0,
+            reviewed_flow_count: 0,
+            truncated: false,
+            batch_results: [],
+            llmFindings: [],
+        };
+    }
+    let env = readLlmRuntimeEnv(options.env);
+    if (options.llmModel) {
+        env = {
+            ...env,
+            model: options.llmModel,
+        };
+    }
+    const target = options.llmMaxFlows > 0 ? summaries.slice(0, options.llmMaxFlows) : summaries;
+    const batchSize = Math.max(1, options.llmBatchSize);
+    const batches = [];
+    for (let index = 0; index < target.length; index += batchSize) {
+        batches.push(target.slice(index, index + batchSize));
+    }
+    const summaryByUuid = Object.fromEntries(summaries.map((summary) => [summary.flow_uuid, summary]));
+    const batchResults = [];
+    const llmFindings = [];
+    for (let index = 0; index < batches.length; index += 1) {
+        const batch = batches[index];
+        const llmPayload = batch.map((summary) => {
+            const serializable = JSON.parse(JSON.stringify(summary));
+            delete serializable._name_fingerprint;
+            return serializable;
+        });
+        try {
+            const response = await invokeLlm({
+                env,
+                input: {
+                    prompt: '你是严谨的LCA flow复审助手。只基于输入证据判断，不得臆造。输出必须是JSON对象。',
+                    context: buildLlmPrompt(llmPayload),
+                },
+                fetchImpl: options.fetchImpl ?? globalThis.fetch,
+                timeoutMs: 45_000,
+                cacheDir: path.join(options.outDir, '.llm-cache'),
+                tracePath: path.join(options.outDir, 'llm-trace.jsonl'),
+                module: 'review-flow',
+                stage: `semantic-review-${index + 1}`,
+                runId: options.runId,
+            });
+            const parsed = parseLlmJsonOutput(response.output);
+            if (!parsed) {
+                batchResults.push({
+                    batch_index: index + 1,
+                    batch_size: batch.length,
+                    enabled: true,
+                    ok: false,
+                    reason: 'llm_non_json_output',
+                    raw_preview: response.output.slice(0, 500),
+                });
+                continue;
+            }
+            const rawFindings = Array.isArray(parsed.findings) ? parsed.findings : [];
+            rawFindings
+                .filter(isRecord)
+                .map((item) => normalizeLlmFinding(item, summaryByUuid, batch.length === 1 ? batch[0].flow_uuid : ''))
+                .filter((item) => item !== null)
+                .forEach((item) => {
+                llmFindings.push(item);
+            });
+            batchResults.push({
+                batch_index: index + 1,
+                batch_size: batch.length,
+                enabled: true,
+                ok: true,
+            });
+        }
+        catch (error) {
+            batchResults.push({
+                batch_index: index + 1,
+                batch_size: batch.length,
+                enabled: true,
+                ok: false,
+                reason: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const deduped = [];
+    const seen = new Set();
+    llmFindings.forEach((finding) => {
+        const key = JSON.stringify({
+            flow_uuid: finding.flow_uuid,
+            severity: finding.severity,
+            fixability: finding.fixability,
+            evidence: finding.evidence ?? {},
+            action: finding.action ?? '',
+        });
+        if (seen.has(key)) {
+            return;
+        }
+        seen.add(key);
+        deduped.push(finding);
+    });
+    return {
+        enabled: true,
+        ok: batchResults.some((item) => item.ok),
+        reason: batchResults.some((item) => item.ok) ? undefined : 'all_batches_failed',
+        batch_count: batches.length,
+        reviewed_flow_count: target.length,
+        truncated: target.length < summaries.length,
+        batch_results: batchResults,
+        llmFindings: deduped,
+    };
+}
+function severityCounts(rows) {
+    const counts = {};
+    rows.forEach((row) => {
+        const key = row.severity;
+        counts[key] = (counts[key] ?? 0) + 1;
+    });
+    return Object.fromEntries(Object.entries(counts).sort(([left], [right]) => left.localeCompare(right)));
+}
+function ruleCounts(rows) {
+    const counts = {};
+    rows.forEach((row) => {
+        const key = coerceText(row.rule_id);
+        counts[key] = (counts[key] ?? 0) + 1;
+    });
+    return Object.fromEntries(Object.entries(counts).sort(([left], [right]) => left.localeCompare(right)));
+}
+function readJsonObject(filePath) {
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+        if (!isRecord(parsed)) {
+            throw new CliError(`Expected JSON object in flow file: ${filePath}`, {
+                code: 'FLOW_REVIEW_INVALID_FLOW_FILE',
+                exitCode: 2,
+            });
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            throw error;
+        }
+        throw new CliError(`Invalid flow JSON file: ${filePath}`, {
+            code: 'FLOW_REVIEW_INVALID_FLOW_FILE',
+            exitCode: 2,
+            details: String(error),
+        });
+    }
+}
+function materializeRowsFile(rowsFile, outDir) {
+    const rows = loadRowsFromFile(rowsFile);
+    const targetDir = path.join(outDir, 'review-input', 'flows');
+    mkdirSync(targetDir, { recursive: true });
+    const byKey = {};
+    let duplicateCount = 0;
+    rows.forEach((row, index) => {
+        const record = extractFlowRecord(row);
+        const flowId = record.id || `row-${index}`;
+        const version = record.version;
+        const key = `${flowId}@${version}`;
+        if (key in byKey) {
+            duplicateCount += 1;
+        }
+        byKey[key] = row;
+    });
+    const items = [];
+    Object.entries(byKey)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .forEach(([key, row]) => {
+        const record = extractFlowRecord(row);
+        const fileName = `${record.id || key.split('@', 1)[0]}__${record.version}.json`;
+        const filePath = path.join(targetDir, fileName);
+        writeJsonArtifact(filePath, {
+            flowDataSet: flowDatasetFromRow(row),
+        });
+        items.push({
+            flow_key: key,
+            primary_name: record.name,
+            file: filePath,
+        });
+    });
+    const summaryPath = path.join(outDir, 'review-input', 'materialization-summary.json');
+    writeJsonArtifact(summaryPath, {
+        source_rows_file: path.resolve(rowsFile),
+        input_row_count: rows.length,
+        materialized_flow_count: Object.keys(byKey).length,
+        duplicate_input_rows_collapsed: duplicateCount,
+        flows_dir: targetDir,
+        items,
+    });
+    return {
+        flowsDir: targetDir,
+        summaryPath,
+    };
+}
+function resolveReviewInput(options) {
+    const declaredModes = [
+        Boolean(options.rowsFile),
+        Boolean(options.flowsDir),
+        Boolean(options.runRoot),
+    ].filter(Boolean);
+    if (declaredModes.length !== 1) {
+        throw new CliError('Flow review requires exactly one of --rows-file, --flows-dir, or --run-root.', {
+            code: 'FLOW_REVIEW_INPUT_MODE_REQUIRED',
+            exitCode: 2,
+        });
+    }
+    if (options.rowsFile) {
+        const materialized = materializeRowsFile(options.rowsFile, options.outDir);
+        return {
+            inputMode: 'rows_file',
+            effectiveFlowsDir: materialized.flowsDir,
+            materializationSummaryPath: materialized.summaryPath,
+            runId: options.runId || path.parse(options.rowsFile).name,
+            reviewInputSummary: {
+                input_mode: 'rows_file',
+                rows_file: path.resolve(options.rowsFile),
+                flows_dir: '',
+                run_root: '',
+                materialized_flows_dir: materialized.flowsDir,
+                effective_flows_dir: materialized.flowsDir,
+            },
+        };
+    }
+    if (options.flowsDir) {
+        const resolved = path.resolve(options.flowsDir);
+        return {
+            inputMode: 'flows_dir',
+            effectiveFlowsDir: resolved,
+            materializationSummaryPath: null,
+            runId: options.runId || path.basename(resolved),
+            reviewInputSummary: {
+                input_mode: 'flows_dir',
+                rows_file: '',
+                flows_dir: resolved,
+                run_root: '',
+                materialized_flows_dir: '',
+                effective_flows_dir: resolved,
+            },
+        };
+    }
+    const runRoot = path.resolve(options.runRoot);
+    const candidates = [path.join(runRoot, 'cache', 'flows'), path.join(runRoot, 'exports', 'flows')];
+    const effective = candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
+    return {
+        inputMode: 'run_root',
+        effectiveFlowsDir: effective,
+        materializationSummaryPath: null,
+        runId: options.runId || path.basename(runRoot),
+        reviewInputSummary: {
+            input_mode: 'run_root',
+            rows_file: '',
+            flows_dir: '',
+            run_root: runRoot,
+            materialized_flows_dir: '',
+            effective_flows_dir: effective,
+        },
+    };
+}
+function listFlowFiles(flowsDir) {
+    if (!existsSync(flowsDir) || !statSync(flowsDir).isDirectory()) {
+        throw new CliError(`Flow review directory not found: ${flowsDir}`, {
+            code: 'FLOW_REVIEW_DIR_NOT_FOUND',
+            exitCode: 2,
+        });
+    }
+    return readdirSync(flowsDir)
+        .filter((entry) => entry.endsWith('.json'))
+        .map((entry) => path.join(flowsDir, entry))
+        .filter((entry) => statSync(entry).isFile())
+        .sort((left, right) => left.localeCompare(right));
+}
+function stripInternalSummaryFields(summary) {
+    const serializable = JSON.parse(JSON.stringify(summary));
+    delete serializable._name_fingerprint;
+    return serializable;
+}
+function renderZhReview(options) {
+    const lines = [
+        '# flow_review_zh\n',
+        `- run_id: \`${options.runId}\`\n`,
+        `- logic_version: \`${options.logicVersion}\`\n`,
+        `- flows_dir: \`${options.flowsDir}\`\n`,
+        `- flow count: \`${options.flowSummaries.length}\`\n`,
+        '- with_reference_context: `false`\n',
+        `- methodology_rule_source: \`${options.summary.methodology_rule_source}\`\n`,
+        '\n## 基础统计\n',
+        `- rule-based findings: **${options.ruleFindings.length}**\n`,
+        `- LLM findings: **${options.llmFindings.length}**\n`,
+        `- merged findings: **${options.mergedFindings.length}**\n`,
+    ];
+    if (options.mergedFindings.length) {
+        lines.push('\n### Severity 统计\n');
+        Object.entries(options.summary.severity_counts).forEach(([key, value]) => {
+            lines.push(`- ${key}: ${value}\n`);
+        });
+    }
+    lines.push('\n## Flow 摘要（最多展示 100 条）\n', '|flow uuid|version|typeOfDataSet|name(en)|class leaf|flow property|规则信号数|相似候选数|\n', '|---|---|---|---|---|---|---:|---:|\n');
+    options.flowSummaries.slice(0, 100).forEach((row) => {
+        const summary = row;
+        lines.push(`|${summary.flow_uuid.replace(/\|/gu, '/')}|${summary.base_version.replace(/\|/gu, '/')}|${summary.type_of_dataset.replace(/\|/gu, '/')}|${summary.names.primary_en.replace(/\|/gu, '/')}|${summary.classification.leaf.text.replace(/\|/gu, '/')}|${coerceText(summary.flow_property.referenced_short_name_en ?? summary.flow_property.referenced_uuid).replace(/\|/gu, '/')}|${summary.rule_signals.length}|${summary.similarity_candidates.length}|\n`);
+    });
+    lines.push('\n## LLM 语义复审层\n');
+    if (!options.llmResult.enabled) {
+        lines.push(`- 未启用：\`${options.llmResult.reason ?? 'disabled'}\`\n`);
+    }
+    else if (!options.llmResult.ok) {
+        lines.push(`- 调用失败：\`${options.llmResult.reason ?? 'unknown'}\`\n`);
+    }
+    else if (!options.llmFindings.length) {
+        lines.push('- 未返回额外语义 findings。\n');
+    }
+    else {
+        if (options.llmResult.truncated) {
+            lines.push(`- 注意：LLM 仅复审前 \`${options.llmResult.reviewed_flow_count}\` 条（受 \`--llm-max-flows\` 限制）。\n`);
+        }
+        lines.push('\n|flow uuid|severity|fixability|evidence|action|\n|---|---|---|---|---|\n');
+        options.llmFindings.slice(0, 200).forEach((finding) => {
+            lines.push(`|${finding.flow_uuid.replace(/\|/gu, '/')}|${finding.severity.replace(/\|/gu, '/')}|${coerceText(finding.fixability).replace(/\|/gu, '/')}|${JSON.stringify(finding.evidence ?? {}).replace(/\|/gu, '/')}|${coerceText(finding.action).replace(/\|/gu, '/')}|\n`);
+        });
+    }
+    lines.push('\n## 说明\n', '- 当前 CLI 版本保持 local-first / artifact-first，不在 review flow 阶段接入 MCP。\n', '- flow property / unitgroup 的额外本地 registry 丰富暂未接入 CLI，本轮 summary 中统一标记为 disabled。\n');
+    return lines.join('');
+}
+function renderEnReview(options) {
+    const lines = [
+        '# flow_review_en\n',
+        `- run_id: \`${options.runId}\`\n`,
+        `- logic_version: \`${options.logicVersion}\`\n`,
+        `- flows_dir: \`${options.flowsDir}\`\n`,
+        `- flow count: \`${options.flowCount}\`\n`,
+        '- with_reference_context: `false`\n',
+        `- methodology_rule_source: \`${options.methodologyRuleSource}\`\n`,
+        '\n## Summary\n',
+        `- rule-based findings: **${options.ruleFindingCount}**\n`,
+        `- llm findings: **${options.llmFindingCount}**\n`,
+    ];
+    if (!options.llmResult.enabled) {
+        lines.push(`- LLM disabled: \`${options.llmResult.reason ?? 'disabled'}\`\n`);
+    }
+    else if (!options.llmResult.ok) {
+        lines.push(`- LLM failed: \`${options.llmResult.reason ?? 'unknown'}\`\n`);
+    }
+    else if (options.llmResult.truncated) {
+        lines.push(`- LLM reviewed only the first \`${options.llmResult.reviewed_flow_count}\` flows due to \`--llm-max-flows\`.\n`);
+    }
+    return lines.join('');
+}
+function renderTimingReview(options) {
+    const lines = ['# flow_review_timing\n', `- run_id: \`${options.runId}\`\n`];
+    if (options.startTs) {
+        lines.push(`- start: \`${options.startTs}\`\n`);
+    }
+    if (options.endTs) {
+        lines.push(`- end: \`${options.endTs}\`\n`);
+    }
+    if (options.startTs && options.endTs) {
+        const started = Date.parse(options.startTs);
+        const ended = Date.parse(options.endTs);
+        if (Number.isFinite(started) && Number.isFinite(ended)) {
+            lines.push(`- total elapsed: **${((ended - started) / 60_000).toFixed(2)} min**\n`);
+        }
+    }
+    lines.push(`- flow files reviewed: \`${options.flowCount}\`\n`);
+    lines.push('- major time consumers: flow JSON parsing, similarity grouping, optional LLM review batches.\n');
+    return lines.join('');
+}
+export async function runFlowReview(options) {
+    if (!options.outDir.trim()) {
+        throw new CliError('Missing required --out-dir value.', {
+            code: 'FLOW_REVIEW_OUT_DIR_REQUIRED',
+            exitCode: 2,
+        });
+    }
+    const outDir = path.resolve(options.outDir);
+    mkdirSync(outDir, { recursive: true });
+    const resolvedInput = resolveReviewInput({
+        ...options,
+        outDir,
+    });
+    const flowFiles = listFlowFiles(resolvedInput.effectiveFlowsDir);
+    if (!flowFiles.length) {
+        throw new CliError(`No flow JSON files found in ${resolvedInput.effectiveFlowsDir}`, {
+            code: 'FLOW_REVIEW_NO_FLOW_FILES',
+            exitCode: 2,
+        });
+    }
+    const methodologyRuleSource = options.methodologyId?.trim() || 'built_in';
+    const ruleFindings = [];
+    const flowSummaries = [];
+    flowFiles.forEach((filePath) => {
+        const doc = readJsonObject(filePath);
+        const { summary, findings } = buildFlowSummaryAndRuleFindings(doc, methodologyRuleSource);
+        summary.source_file = path.basename(filePath);
+        flowSummaries.push(summary);
+        ruleFindings.push(...findings);
+    });
+    const similarity = buildSimilarity(flowSummaries, options.similarityThreshold ?? 0.92);
+    flowSummaries.forEach((summary) => {
+        summary.similarity_candidates = similarity.candidatesByFlow[summary.flow_uuid] ?? [];
+        if (!summary.similarity_candidates.length) {
+            return;
+        }
+        ruleFindings.push(createRuleFinding(summary.flow_uuid, summary.base_version, 'warning', 'same_category_high_similarity', 'Another flow in the same classification/flowProperty/unitgroup group is highly similar.', {
+            fixability: 'review-needed',
+            evidence: {
+                candidates: summary.similarity_candidates.slice(0, 3),
+            },
+        }));
+    });
+    const llmRun = await runOptionalLlmReview(flowSummaries, {
+        enableLlm: Boolean(options.enableLlm),
+        llmModel: options.llmModel,
+        llmMaxFlows: options.llmMaxFlows ?? 120,
+        llmBatchSize: options.llmBatchSize ?? 20,
+        env: options.env ?? process.env,
+        fetchImpl: options.fetchImpl,
+        outDir,
+        runId: resolvedInput.runId,
+    });
+    const llmResult = {
+        enabled: llmRun.enabled,
+        ...(llmRun.ok === undefined ? {} : { ok: llmRun.ok }),
+        ...(llmRun.reason ? { reason: llmRun.reason } : {}),
+        batch_count: llmRun.batch_count,
+        reviewed_flow_count: llmRun.reviewed_flow_count,
+        truncated: llmRun.truncated,
+        batch_results: llmRun.batch_results,
+    };
+    const mergedFindings = [...ruleFindings, ...llmRun.llmFindings];
+    const savedSummaries = flowSummaries.map((summary) => stripInternalSummaryFields(summary));
+    const now = options.now ?? (() => new Date());
+    const reviewInputSummaryPath = path.join(outDir, 'review-input-summary.json');
+    const ruleFindingsPath = path.join(outDir, 'rule_findings.jsonl');
+    const llmFindingsPath = path.join(outDir, 'llm_findings.jsonl');
+    const findingsPath = path.join(outDir, 'findings.jsonl');
+    const flowSummariesPath = path.join(outDir, 'flow_summaries.jsonl');
+    const similarityPairsPath = path.join(outDir, 'similarity_pairs.jsonl');
+    const summaryPath = path.join(outDir, 'flow_review_summary.json');
+    const reviewZhPath = path.join(outDir, 'flow_review_zh.md');
+    const reviewEnPath = path.join(outDir, 'flow_review_en.md');
+    const timingPath = path.join(outDir, 'flow_review_timing.md');
+    const reportPath = path.join(outDir, 'flow_review_report.json');
+    writeJsonArtifact(reviewInputSummaryPath, resolvedInput.reviewInputSummary);
+    writeJsonLinesArtifact(ruleFindingsPath, ruleFindings);
+    writeJsonLinesArtifact(llmFindingsPath, llmRun.llmFindings);
+    writeJsonLinesArtifact(findingsPath, mergedFindings);
+    writeJsonLinesArtifact(flowSummariesPath, savedSummaries);
+    writeJsonLinesArtifact(similarityPairsPath, similarity.pairs);
+    const report = {
+        schema_version: 1,
+        generated_at_utc: now().toISOString(),
+        status: 'completed_local_flow_review',
+        run_id: resolvedInput.runId,
+        out_dir: outDir,
+        input_mode: resolvedInput.inputMode,
+        effective_flows_dir: resolvedInput.effectiveFlowsDir,
+        logic_version: options.logicVersion?.trim() || 'flow-v1.0-cli',
+        flow_count: flowSummaries.length,
+        similarity_threshold: options.similarityThreshold ?? 0.92,
+        methodology_rule_source: methodologyRuleSource,
+        with_reference_context: false,
+        reference_context_mode: 'disabled',
+        rule_finding_count: ruleFindings.length,
+        llm_finding_count: llmRun.llmFindings.length,
+        finding_count: mergedFindings.length,
+        severity_counts: severityCounts(mergedFindings),
+        rule_counts: ruleCounts(ruleFindings),
+        llm: llmResult,
+        files: {
+            review_input_summary: reviewInputSummaryPath,
+            materialization_summary: resolvedInput.materializationSummaryPath,
+            rule_findings: ruleFindingsPath,
+            llm_findings: llmFindingsPath,
+            findings: findingsPath,
+            flow_summaries: flowSummariesPath,
+            similarity_pairs: similarityPairsPath,
+            summary: summaryPath,
+            review_zh: reviewZhPath,
+            review_en: reviewEnPath,
+            timing: timingPath,
+            report: reportPath,
+        },
+    };
+    writeJsonArtifact(summaryPath, {
+        run_id: report.run_id,
+        logic_version: report.logic_version,
+        flow_count: report.flow_count,
+        with_reference_context: report.with_reference_context,
+        reference_context_mode: report.reference_context_mode,
+        similarity_threshold: report.similarity_threshold,
+        methodology_rule_source: report.methodology_rule_source,
+        rule_finding_count: report.rule_finding_count,
+        llm_finding_count: report.llm_finding_count,
+        finding_count: report.finding_count,
+        severity_counts: report.severity_counts,
+        rule_counts: report.rule_counts,
+        llm: report.llm,
+    });
+    writeTextArtifact(reviewZhPath, renderZhReview({
+        runId: report.run_id,
+        logicVersion: report.logic_version,
+        flowsDir: report.effective_flows_dir,
+        flowSummaries: savedSummaries,
+        ruleFindings,
+        llmFindings: llmRun.llmFindings,
+        llmResult,
+        mergedFindings,
+        summary: report,
+    }));
+    writeTextArtifact(reviewEnPath, renderEnReview({
+        runId: report.run_id,
+        logicVersion: report.logic_version,
+        flowsDir: report.effective_flows_dir,
+        flowCount: report.flow_count,
+        ruleFindingCount: report.rule_finding_count,
+        llmFindingCount: report.llm_finding_count,
+        llmResult,
+        methodologyRuleSource: report.methodology_rule_source,
+    }));
+    writeTextArtifact(timingPath, renderTimingReview({
+        runId: report.run_id,
+        startTs: options.startTs,
+        endTs: options.endTs,
+        flowCount: report.flow_count,
+    }));
+    writeJsonArtifact(reportPath, report);
+    return report;
+}
+export const __testInternals = {
+    applyMethodologyChecks,
+    buildFlowSummaryAndRuleFindings,
+    buildSimilarity,
+    buildLlmPrompt,
+    classificationLeaf,
+    computeSimilarity,
+    createRuleFinding,
+    findUuidInNode,
+    flowRoot,
+    langTextForLang,
+    listFlowFiles,
+    materializeRowsFile,
+    nameFingerprint,
+    normalizeLlmFinding,
+    parseLlmJsonOutput,
+    readJsonObject,
+    renderEnReview,
+    renderTimingReview,
+    renderZhReview,
+    resolveReviewInput,
+    runOptionalLlmReview,
+    ruleCounts,
+    severityCounts,
+    walkStrings,
+};
+//# sourceMappingURL=review-flow.js.map