@tiangong-lca/cli 0.0.11 → 0.0.13

package/dist/src/lib/dataset-classification.js

@@ -0,0 +1,947 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writeJsonArtifact, writeJsonLinesArtifact } from './artifacts.js';
+import { cloneJson, firstNonEmpty, isRecord, readDatasetRowsInput, trimToken, unwrapDatasetPayload, } from './dataset-local.js';
+import { CliError } from './errors.js';
+import { readJsonInput } from './io.js';
+const CATEGORY_CONFIGS = {
+    contact: {
+        type: 'contact',
+        schemaFile: 'tidas_contacts_category.json',
+        defaultValueKey: '@classId',
+        target: 'common:class',
+    },
+    'flow-elementary': {
+        type: 'flow-elementary',
+        schemaFile: 'tidas_flows_elementary_category.json',
+        defaultValueKey: '@catId',
+        target: 'common:category',
+    },
+    'flow-product': {
+        type: 'flow-product',
+        schemaFile: 'tidas_flows_product_category.json',
+        defaultValueKey: '@classId',
+        target: 'common:class',
+    },
+    flowproperty: {
+        type: 'flowproperty',
+        schemaFile: 'tidas_flowproperties_category.json',
+        defaultValueKey: '@classId',
+        target: 'common:class',
+    },
+    lciamethod: {
+        type: 'lciamethod',
+        schemaFile: 'tidas_lciamethods_category.json',
+        defaultValueKey: '@classId',
+        target: 'common:class',
+    },
+    location: {
+        type: 'location',
+        schemaFile: 'tidas_locations_category.json',
+        defaultValueKey: '@code',
+        target: 'location',
+    },
+    process: {
+        type: 'process',
+        schemaFile: 'tidas_processes_category.json',
+        defaultValueKey: '@classId',
+        target: 'common:class',
+    },
+    source: {
+        type: 'source',
+        schemaFile: 'tidas_sources_category.json',
+        defaultValueKey: '@classId',
+        target: 'common:class',
+    },
+    unitgroup: {
+        type: 'unitgroup',
+        schemaFile: 'tidas_unitgroups_category.json',
+        defaultValueKey: '@classId',
+        target: 'common:class',
+    },
+};
+const DATASET_ROOTS = [
+    { rootKey: 'contactDataSet', informationKey: 'contactInformation', type: 'contact' },
+    { rootKey: 'flowDataSet', informationKey: 'flowInformation', type: 'flow-product' },
+    {
+        rootKey: 'flowPropertyDataSet',
+        informationKey: 'flowPropertiesInformation',
+        type: 'flowproperty',
+    },
+    { rootKey: 'LCIAMethodDataSet', informationKey: 'LCIAMethodInformation', type: 'lciamethod' },
+    {
+        rootKey: 'lifeCycleModelDataSet',
+        informationKey: 'lifeCycleModelInformation',
+        type: 'lifecyclemodel',
+    },
+    { rootKey: 'processDataSet', informationKey: 'processInformation', type: 'process' },
+    { rootKey: 'sourceDataSet', informationKey: 'sourceInformation', type: 'source' },
+    { rootKey: 'unitGroupDataSet', informationKey: 'unitGroupInformation', type: 'unitgroup' },
+];
+const TYPE_ALIASES = {
+    contact: 'contact',
+    contacts: 'contact',
+    elementary: 'flow-elementary',
+    elementaryflow: 'flow-elementary',
+    elementaryflows: 'flow-elementary',
+    'elementary-flow': 'flow-elementary',
+    'elementary-flows': 'flow-elementary',
+    flowelementary: 'flow-elementary',
+    'flow-elementary': 'flow-elementary',
+    flowproduct: 'flow-product',
+    flowproducts: 'flow-product',
+    'flow-product': 'flow-product',
+    'flow-products': 'flow-product',
+    flows: 'flow-product',
+    product: 'flow-product',
+    productflow: 'flow-product',
+    productflows: 'flow-product',
+    'product-flow': 'flow-product',
+    'product-flows': 'flow-product',
+    flowproperties: 'flowproperty',
+    flowproperty: 'flowproperty',
+    lcia: 'lciamethod',
+    lciamethod: 'lciamethod',
+    lciamethods: 'lciamethod',
+    location: 'location',
+    locations: 'location',
+    process: 'process',
+    processes: 'process',
+    source: 'source',
+    sources: 'source',
+    unitgroup: 'unitgroup',
+    unitgroups: 'unitgroup',
+};
+function normalizeType(value) {
+    const token = trimToken(value)
+        ?.toLowerCase()
+        .replace(/[_\s]+/gu, '-');
+    const normalized = token ? (TYPE_ALIASES[token] ?? TYPE_ALIASES[token.replace(/-/gu, '')]) : null;
+    if (!normalized) {
+        throw new CliError(`Unsupported classification type: ${String(value ?? '')}`, {
+            code: 'CLASSIFICATION_TYPE_UNSUPPORTED',
+            exitCode: 2,
+        });
+    }
+    return normalized;
+}
+function schemasDir(candidatesOverride) {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = candidatesOverride ?? [
+        path.resolve(here, '../../assets/tidas-schemas'),
+        path.resolve(here, '../../../assets/tidas-schemas'),
+        path.resolve(process.cwd(), 'assets/tidas-schemas'),
+    ];
+    const found = candidates.find((candidate) => existsSync(candidate));
+    if (!found) {
+        throw new CliError('Bundled TIDAS schemas were not found under assets/tidas-schemas.', {
+            code: 'TIDAS_SCHEMAS_NOT_FOUND',
+            exitCode: 2,
+        });
+    }
+    return found;
+}
+function schemaPath(config) {
+    return path.join(schemasDir(), config.schemaFile);
+}
+const FALLBACK_LOCATION_TARGET_KEYS = new Set([
+    '@location',
+    '@subLocation',
+    'impactLocation',
+    'impactSubLocation',
+    'interventionLocation',
+    'interventionSubLocation',
+    'intervensionSubLocation',
+    'location',
+    'locationOfSupply',
+    'subLocation',
+]);
+let cachedLocationTargetKeys = null;
+function lastSchemaPropertyName(schemaPathSegments) {
+    let propertyName = null;
+    for (let index = 0; index < schemaPathSegments.length - 1; index += 1) {
+        if (schemaPathSegments[index] === 'properties') {
+            propertyName = schemaPathSegments[index + 1];
+        }
+    }
+    return propertyName;
+}
+function collectLocationRefKeysFromSchema(value, schemaPathSegments, keys) {
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => collectLocationRefKeysFromSchema(item, [...schemaPathSegments, String(index)], keys));
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    if (value.$ref === 'tidas_locations_category.json') {
+        const propertyName = lastSchemaPropertyName(schemaPathSegments);
+        if (propertyName)
+            keys.add(propertyName);
+    }
+    for (const [key, child] of Object.entries(value)) {
+        collectLocationRefKeysFromSchema(child, [...schemaPathSegments, key], keys);
+    }
+}
+function locationTargetKeys() {
+    if (cachedLocationTargetKeys)
+        return cachedLocationTargetKeys;
+    const keys = new Set();
+    const dir = schemasDir();
+    for (const fileName of readdirSync(dir).filter(isJsonSchemaFileName)) {
+        const document = JSON.parse(readFileSync(path.join(dir, fileName), 'utf8'));
+        collectLocationRefKeysFromSchema(document, [], keys);
+    }
+    cachedLocationTargetKeys = new Set([...FALLBACK_LOCATION_TARGET_KEYS, ...keys]);
+    return cachedLocationTargetKeys;
+}
+function isJsonSchemaFileName(fileName) {
+    return fileName.endsWith('.json');
+}
+function constText(value) {
+    return isRecord(value) ? firstNonEmpty(value.const) : null;
+}
+function collectEntriesFromNode(node, defaultValueKey, entries) {
+    if (Array.isArray(node)) {
+        node.forEach((entry) => collectEntriesFromNode(entry, defaultValueKey, entries));
+        return;
+    }
+    if (!isRecord(node))
+        return;
+    if (isRecord(node.properties)) {
+        const properties = node.properties;
+        const level = firstNonEmpty(constText(properties['@level']), '0');
+        const valueKey = ['@classId', '@catId', '@code'].find((key) => constText(properties[key])) ??
+            defaultValueKey;
+        const code = constText(properties[valueKey]);
+        const text = constText(properties['#text']);
+        if (level && code && text) {
+            const parsedLevel = Number(level);
+            if (Number.isInteger(parsedLevel)) {
+                entries.push({ level: parsedLevel, code, text, value_key: valueKey });
+            }
+        }
+    }
+    else if (node.const !== undefined && typeof node.description === 'string') {
+        entries.push({
+            level: 0,
+            code: String(node.const),
+            text: node.description,
+            value_key: '@code',
+        });
+    }
+    for (const value of Object.values(node)) {
+        if (isRecord(value) || Array.isArray(value)) {
+            collectEntriesFromNode(value, defaultValueKey, entries);
+        }
+    }
+}
+function loadEntries(type) {
+    const config = CATEGORY_CONFIGS[type];
+    const schema = schemaPath(config);
+    const document = JSON.parse(readFileSync(schema, 'utf8'));
+    const entries = [];
+    collectEntriesFromNode(document, config.defaultValueKey, entries);
+    return { config, schema, entries };
+}
+function buildNavigator(entries) {
+    const childMap = new Map();
+    const parentMap = new Map();
+    const entriesByCode = new Map();
+    const lastPerLevel = new Map();
+    for (const entry of entries) {
+        entriesByCode.set(entry.code, entry);
+        if (entry.level === 0) {
+            const roots = childMap.get('') ?? [];
+            roots.push(entry);
+            childMap.set('', roots);
+            parentMap.set(entry.code, null);
+        }
+        else {
+            let parent = null;
+            for (let level = entry.level - 1; level >= 0; level -= 1) {
+                parent = lastPerLevel.get(level) ?? null;
+                if (parent)
+                    break;
+            }
+            if (parent) {
+                const children = childMap.get(parent.code) ?? [];
+                children.push(entry);
+                childMap.set(parent.code, children);
+                parentMap.set(entry.code, parent);
+            }
+        }
+        lastPerLevel.set(entry.level, entry);
+    }
+    return { entries, entriesByCode, childMap, parentMap };
+}
+function navigatorFor(type) {
+    const { config, schema, entries } = loadEntries(type);
+    return { config, schema, navigator: buildNavigator(entries) };
+}
+function pathForCode(navigator, code) {
+    const entry = navigator.entriesByCode.get(code);
+    if (!entry)
+        return [];
+    const pathEntries = [entry];
+    let current = entry;
+    while (true) {
+        const parent = navigator.parentMap.get(current.code);
+        if (!parent)
+            break;
+        pathEntries.push(parent);
+        current = parent;
+    }
+    return pathEntries.reverse();
+}
+function toPathEntry(entry) {
+    return {
+        '@level': String(entry.level),
+        [entry.value_key]: entry.code,
+        '#text': entry.text,
+    };
+}
+function classCode(value) {
+    return isRecord(value)
+        ? firstNonEmpty(value['@classId'], value['@catId'], value['@code'], value.class_id, value.classId, value.cat_id, value.catId, value.code)
+        : null;
+}
+function pathExpression(pathSegments) {
+    return pathSegments.map(String).join('.');
+}
+function normalizeTargetPath(value) {
+    const raw = firstNonEmpty(value);
+    if (!raw)
+        return null;
+    if (raw.startsWith('/')) {
+        return raw
+            .split('/')
+            .slice(1)
+            .map((segment) => segment.replace(/~1/gu, '/').replace(/~0/gu, '~'))
+            .join('.');
+    }
+    return raw;
+}
+function decisionTargetPath(decision) {
+    return normalizeTargetPath(decision.target_path ??
+        decision.targetPath ??
+        decision.field_path ??
+        decision.fieldPath ??
+        decision.location_path ??
+        decision.locationPath ??
+        decision.json_pointer ??
+        decision.jsonPointer);
+}
+function normalizePathFromClasses(type, classes) {
+    const { navigator } = navigatorFor(type);
+    const rawClasses = Array.isArray(classes) ? classes : isRecord(classes) ? [classes] : [];
+    if (rawClasses.length === 0)
+        return [];
+    const leafCode = classCode(rawClasses[rawClasses.length - 1]);
+    if (!leafCode)
+        return [];
+    const canonical = pathForCode(navigator, leafCode);
+    const rawCodes = rawClasses.map(classCode).filter(Boolean);
+    const canonicalCodes = canonical.map((entry) => entry.code);
+    if (rawCodes.length > 0 &&
+        rawCodes.join('/') !== canonicalCodes.slice(0, rawCodes.length).join('/')) {
+        return [];
+    }
+    return canonical.map(toPathEntry);
+}
+function normalizePathFromDecision(type, decision) {
+    const explicit = decision.classes ??
+        decision.classification_classes ??
+        (isRecord(decision.classification)
+            ? (decision.classification['common:class'] ??
+                decision.classification['common:category'] ??
+                decision.classification.classes)
+            : null);
+    const explicitPath = normalizePathFromClasses(type, explicit);
+    if (explicitPath.length > 0)
+        return explicitPath;
+    const directCode = firstNonEmpty(decision.code, decision.class_id, decision.classId, decision.cat_id, decision.catId, decision.leaf_code, decision.leafCode);
+    if (directCode) {
+        const { navigator } = navigatorFor(type);
+        return pathForCode(navigator, directCode).map(toPathEntry);
+    }
+    const rawLabels = decision.classification_path ?? decision.classificationPath;
+    const rawIds = decision.class_ids ?? decision.classIds;
+    const labels = Array.isArray(rawLabels) ? rawLabels : [];
+    const ids = Array.isArray(rawIds) ? rawIds : [];
+    if (labels.length > 0 && labels.length === ids.length) {
+        return normalizePathFromClasses(type, labels.map((label, index) => ({
+            '@level': String(index),
+            '@classId': ids[index],
+            '#text': label,
+        })));
+    }
+    return [];
+}
+function normalizeDecisionType(decision, fallbackType) {
+    const raw = firstNonEmpty(decision.category_type, decision.categoryType, decision.classification_type, decision.classificationType, decision.type);
+    return raw ? normalizeType(raw) : fallbackType;
+}
+function readJsonLines(filePath) {
+    return readFileSync(filePath, 'utf8')
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line, index) => {
+        const parsed = JSON.parse(line);
+        if (!isRecord(parsed)) {
+            throw new CliError(`Classification decision line ${index + 1} is not an object.`, {
+                code: 'CLASSIFICATION_DECISION_INVALID',
+                exitCode: 2,
+            });
+        }
+        return parsed;
+    });
+}
+function normalizeStructuredDecisions(value) {
+    if (Array.isArray(value))
+        return value.filter(isRecord);
+    if (isRecord(value) && Array.isArray(value.decisions))
+        return value.decisions.filter(isRecord);
+    if (isRecord(value) && Array.isArray(value.rows))
+        return value.rows.filter(isRecord);
+    return isRecord(value) ? [value] : [];
+}
+function readDecisions(pathValue, rawInput) {
+    if (!pathValue) {
+        throw new CliError('Missing required --decisions value.', {
+            code: 'CLASSIFICATION_DECISIONS_REQUIRED',
+            exitCode: 2,
+        });
+    }
+    if (rawInput !== undefined)
+        return normalizeStructuredDecisions(rawInput);
+    const resolved = path.resolve(pathValue);
+    if (!existsSync(resolved)) {
+        throw new CliError(`Classification decisions file not found: ${resolved}`, {
+            code: 'CLASSIFICATION_DECISIONS_NOT_FOUND',
+            exitCode: 2,
+        });
+    }
+    return resolved.toLowerCase().endsWith('.jsonl')
+        ? readJsonLines(resolved)
+        : normalizeStructuredDecisions(readJsonInput(resolved));
+}
+function prepareRows(inputPath, rawInput) {
+    return readDatasetRowsInput(inputPath, rawInput).map((row, index) => {
+        const clonedRow = cloneJson(row);
+        const payload = unwrapDatasetPayload(clonedRow);
+        const descriptor = DATASET_ROOTS.find((candidate) => isRecord(payload[candidate.rootKey]));
+        const root = descriptor ? payload[descriptor.rootKey] : {};
+        const info = descriptor && isRecord(root[descriptor.informationKey])
+            ? root[descriptor.informationKey]
+            : {};
+        const dataSetInformation = isRecord(info.dataSetInformation)
+            ? info.dataSetInformation
+            : {};
+        const administrativeInformation = isRecord(root.administrativeInformation)
+            ? root.administrativeInformation
+            : {};
+        const publicationAndOwnership = isRecord(administrativeInformation.publicationAndOwnership)
+            ? administrativeInformation.publicationAndOwnership
+            : {};
+        return {
+            index,
+            row: clonedRow,
+            payload,
+            rootKey: descriptor?.rootKey ?? null,
+            informationKey: descriptor?.informationKey ?? null,
+            id: firstNonEmpty(clonedRow.id, dataSetInformation['common:UUID']),
+            version: firstNonEmpty(clonedRow.version, publicationAndOwnership['common:dataSetVersion']),
+        };
+    });
+}
+function classificationContainer(row, type) {
+    if (CATEGORY_CONFIGS[type].target === 'location')
+        return null;
+    if (!row.rootKey || !row.informationKey)
+        return null;
+    const root = row.payload[row.rootKey];
+    if (!isRecord(root))
+        return null;
+    const info = root[row.informationKey];
+    if (!isRecord(info))
+        return null;
+    if (!isRecord(info.dataSetInformation))
+        info.dataSetInformation = {};
+    const dataSetInformation = info.dataSetInformation;
+    if (!isRecord(dataSetInformation.classificationInformation)) {
+        dataSetInformation.classificationInformation = {};
+    }
+    const classificationInformation = dataSetInformation.classificationInformation;
+    const target = CATEGORY_CONFIGS[type].target;
+    if (target === 'common:category') {
+        if (!isRecord(classificationInformation['common:elementaryFlowCategorization'])) {
+            classificationInformation['common:elementaryFlowCategorization'] = {};
+        }
+        return classificationInformation['common:elementaryFlowCategorization'];
+    }
+    if (!isRecord(classificationInformation['common:classification'])) {
+        classificationInformation['common:classification'] = {};
+    }
+    return classificationInformation['common:classification'];
+}
+function currentClassification(row, type) {
+    const container = classificationContainer(row, type);
+    if (!container)
+        return null;
+    return CATEGORY_CONFIGS[type].target === 'common:category'
+        ? container['common:category']
+        : container['common:class'];
+}
+function setClassification(row, type, classificationPath) {
+    const container = classificationContainer(row, type);
+    if (!container)
+        return false;
+    if (CATEGORY_CONFIGS[type].target === 'common:category') {
+        container['common:category'] = cloneJson(classificationPath);
+    }
+    else {
+        container['common:class'] = cloneJson(classificationPath);
+    }
+    return true;
+}
+function isLocationTargetKey(key) {
+    return locationTargetKeys().has(key);
+}
+function locationTargetStringValue(value) {
+    if (typeof value === 'string') {
+        return {
+            parent: null,
+            key: null,
+            pathSuffix: [],
+            value: value.trim(),
+        };
+    }
+    if (isRecord(value) && typeof value['#text'] === 'string') {
+        return {
+            parent: value,
+            key: '#text',
+            pathSuffix: ['#text'],
+            value: value['#text'].trim(),
+        };
+    }
+    return null;
+}
+function collectLocationTargets(value, pathSegments = [], targets = []) {
+    if (!isRecord(value)) {
+        if (Array.isArray(value)) {
+            value.forEach((item, index) => collectLocationTargets(item, [...pathSegments, index], targets));
+        }
+        return targets;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        const childPath = [...pathSegments, key];
+        if (isLocationTargetKey(key)) {
+            const targetValue = locationTargetStringValue(child);
+            if (targetValue) {
+                const leafPath = [...childPath, ...targetValue.pathSuffix];
+                const parent = targetValue.pathSuffix.length > 0 ? targetValue.parent : value;
+                const targetKey = targetValue.pathSuffix.length > 0 ? targetValue.key : key;
+                targets.push({
+                    path: pathExpression(leafPath),
+                    parentPath: pathExpression(targetValue.pathSuffix.length > 0 ? childPath : pathSegments),
+                    parent: parent,
+                    key: targetKey,
+                    value: targetValue.value,
+                });
+            }
+        }
+        collectLocationTargets(child, childPath, targets);
+    }
+    return targets;
+}
+function locationCodeFromPath(classificationPath) {
+    const leaf = classificationPath.at(-1);
+    return classCode(leaf);
+}
+function resolveLocationTarget(row, decision) {
+    const targets = collectLocationTargets(row.payload);
+    if (!decision.targetPath)
+        return targets;
+    return targets.filter((target) => target.path === decision.targetPath || target.parentPath === decision.targetPath);
+}
+function decisionMatchesRow(decision, row) {
+    if (decision.rowIndex !== null)
+        return decision.rowIndex === row.index;
+    if (!decision.datasetId || decision.datasetId !== row.id)
+        return false;
+    return !decision.datasetVersion || decision.datasetVersion === row.version;
+}
+function normalizeDecision(decision, decisionIndex, fallbackType, blockers) {
+    const rawRowIndex = decision.row_index ?? decision.rowIndex;
+    const rowIndexText = firstNonEmpty(rawRowIndex);
+    const rowIndex = typeof rawRowIndex === 'number'
+        ? rawRowIndex
+        : rowIndexText === null
+            ? null
+            : Number(rowIndexText);
+    const validRowIndex = typeof rowIndex === 'number' && Number.isInteger(rowIndex) ? rowIndex : null;
+    const datasetId = firstNonEmpty(decision.dataset_id, decision.datasetId, decision.id, decision.uuid);
+    const datasetVersion = firstNonEmpty(decision.dataset_version, decision.datasetVersion, decision.version);
+    const categoryType = normalizeDecisionType(decision, fallbackType);
+    if (validRowIndex === null && !datasetId) {
+        blockers.push({
+            code: 'classification_decision_target_missing',
+            message: 'Classification decision must target row_index or dataset_id.',
+            decision_index: decisionIndex,
+        });
+        return null;
+    }
+    if (!categoryType) {
+        blockers.push({
+            code: 'classification_decision_type_missing',
+            message: 'Classification decision must provide a category_type or the command must pass --type.',
+            decision_index: decisionIndex,
+            row_index: validRowIndex ?? undefined,
+            dataset_id: datasetId,
+            dataset_version: datasetVersion,
+        });
+        return null;
+    }
+    const classificationPath = normalizePathFromDecision(categoryType, decision);
+    if (classificationPath.length === 0) {
+        blockers.push({
+            code: 'classification_decision_path_invalid',
+            message: 'Classification decision must resolve to a valid path in the bundled TIDAS category schema.',
+            decision_index: decisionIndex,
+            row_index: validRowIndex ?? undefined,
+            dataset_id: datasetId,
+            dataset_version: datasetVersion,
+        });
+        return null;
+    }
+    return {
+        decisionIndex,
+        rowIndex: validRowIndex,
+        datasetId,
+        datasetVersion,
+        categoryType,
+        path: classificationPath,
+        targetPath: decisionTargetPath(decision),
+        basis: firstNonEmpty(decision.basis),
+        evidence: decision.evidence ?? null,
+    };
+}
+function maybeWriteReport(report, outDir, filename) {
+    if (!outDir)
+        return report;
+    const reportPath = path.join(path.resolve(outDir), 'outputs', filename);
+    const finalReport = { ...report, files: { report: reportPath } };
+    writeJsonArtifact(reportPath, finalReport);
+    return finalReport;
+}
+export async function runDatasetClassificationChildren(options) {
+    const type = normalizeType(options.type);
+    const { config, navigator } = navigatorFor(type);
+    const parentCode = firstNonEmpty(options.parent);
+    const rawChildren = navigator.childMap.get(parentCode ?? '') ?? [];
+    const parentKnown = !parentCode || navigator.entriesByCode.has(parentCode);
+    const query = firstNonEmpty(options.query)?.toLowerCase() ?? null;
+    const filtered = query
+        ? rawChildren.filter((entry) => entry.code.toLowerCase().includes(query) || entry.text.toLowerCase().includes(query))
+        : rawChildren;
+    const limit = options.limit && options.limit > 0 ? options.limit : null;
+    const returned = limit ? filtered.slice(0, limit) : filtered;
+    const report = {
+        schema_version: 1,
+        generated_at_utc: (options.now ?? new Date()).toISOString(),
+        status: parentKnown ? 'completed' : 'blocked',
+        command: 'dataset classification children',
+        category_type: type,
+        schema_file: config.schemaFile,
+        parent_code: parentCode,
+        query,
+        counts: {
+            children: rawChildren.length,
+            returned: returned.length,
+        },
+        children: returned.map((entry) => ({
+            ...entry,
+            path: pathForCode(navigator, entry.code).map(toPathEntry),
+        })),
+        blockers: parentKnown
+            ? []
+            : [{ code: 'classification_parent_unknown', message: `Unknown parent code: ${parentCode}` }],
+    };
+    return maybeWriteReport(report, options.outDir, 'classification-children-report.json');
+}
+export async function runDatasetClassificationPath(options) {
+    const type = normalizeType(options.type);
+    const { config, navigator } = navigatorFor(type);
+    const code = firstNonEmpty(options.code);
+    if (!code) {
+        throw new CliError('Missing required --code value.', {
+            code: 'CLASSIFICATION_CODE_REQUIRED',
+            exitCode: 2,
+        });
+    }
+    const pathEntries = pathForCode(navigator, code).map(toPathEntry);
+    const report = {
+        schema_version: 1,
+        generated_at_utc: (options.now ?? new Date()).toISOString(),
+        status: pathEntries.length > 0 ? 'completed' : 'blocked',
+        command: 'dataset classification path',
+        category_type: type,
+        schema_file: config.schemaFile,
+        code,
+        path: pathEntries,
+        blockers: pathEntries.length > 0
+            ? []
+            : [
+                {
+                    code: 'classification_code_unknown',
+                    message: `Unknown classification code: ${code}`,
+                },
+            ],
+    };
+    return maybeWriteReport(report, options.outDir, 'classification-path-report.json');
+}
+export async function runDatasetClassificationAudit(options) {
+    if (!options.inputPath) {
+        throw new CliError('Missing required --input value.', {
+            code: 'CLASSIFICATION_AUDIT_INPUT_REQUIRED',
+            exitCode: 2,
+        });
+    }
+    const type = normalizeType(options.type);
+    if (type !== 'location') {
+        throw new CliError('dataset classification audit currently supports only --type location.', {
+            code: 'CLASSIFICATION_AUDIT_TYPE_UNSUPPORTED',
+            exitCode: 2,
+        });
+    }
+    const { config, navigator } = navigatorFor(type);
+    const rows = prepareRows(options.inputPath, options.rawInput);
+    const findings = [];
+    const blockers = [];
+    for (const row of rows) {
+        for (const target of collectLocationTargets(row.payload)) {
+            const entry = navigator.entriesByCode.get(target.value);
+            const status = entry ? 'valid' : 'invalid';
+            findings.push({
+                row_index: row.index,
+                dataset_id: row.id,
+                dataset_version: row.version,
+                path: target.path,
+                value: target.value,
+                status,
+                description: entry?.text ?? null,
+            });
+            if (!entry) {
+                blockers.push({
+                    code: 'location_code_invalid',
+                    message: 'Location value is not a code from the bundled TIDAS location schema.',
+                    row_index: row.index,
+                    dataset_id: row.id,
+                    dataset_version: row.version,
+                });
+            }
+        }
+    }
+    const invalid = findings.filter((finding) => finding.status === 'invalid').length;
+    const outDir = options.outDir ? path.resolve(options.outDir) : null;
+    const findingsPath = outDir
+        ? path.join(outDir, 'outputs', 'location-audit-findings.jsonl')
+        : null;
+    const reportPath = outDir ? path.join(outDir, 'outputs', 'location-audit-report.json') : null;
+    const report = {
+        schema_version: 1,
+        generated_at_utc: (options.now ?? new Date()).toISOString(),
+        status: invalid > 0 ? 'blocked' : 'completed',
+        command: 'dataset classification audit',
+        category_type: type,
+        schema_file: config.schemaFile,
+        input_path: path.resolve(options.inputPath),
+        counts: {
+            rows: rows.length,
+            location_targets: findings.length,
+            valid: findings.length - invalid,
+            invalid,
+        },
+        findings,
+        blockers,
+        ...(findingsPath && reportPath
+            ? {
+                files: {
+                    findings: findingsPath,
+                    report: reportPath,
+                },
+            }
+            : {}),
+    };
+    if (findingsPath && reportPath) {
+        writeJsonLinesArtifact(findingsPath, findings);
+        writeJsonArtifact(reportPath, report);
+    }
+    return report;
+}
+export async function runDatasetClassificationApply(options) {
+    if (!options.inputPath) {
+        throw new CliError('Missing required --input value.', {
+            code: 'CLASSIFICATION_INPUT_REQUIRED',
+            exitCode: 2,
+        });
+    }
+    if (!options.outPath) {
+        throw new CliError('Missing required --out value.', {
+            code: 'CLASSIFICATION_OUT_REQUIRED',
+            exitCode: 2,
+        });
+    }
+    const fallbackType = options.type ? normalizeType(options.type) : null;
+    const rows = prepareRows(options.inputPath, options.rawInput);
+    const rawDecisions = readDecisions(options.decisionsPath, options.rawDecisions);
+    const blockers = [];
+    const decisions = rawDecisions
+        .map((decision, index) => normalizeDecision(decision, index, fallbackType, blockers))
+        .filter((decision) => Boolean(decision));
+    const evidence = [];
+    for (const decision of decisions) {
+        const matches = rows.filter((row) => decisionMatchesRow(decision, row));
+        if (matches.length !== 1) {
+            blockers.push({
+                code: matches.length === 0
+                    ? 'classification_target_not_found'
+                    : 'classification_target_ambiguous',
+                message: matches.length === 0
+                    ? 'Classification decision did not match an input row.'
+                    : 'Classification decision matched more than one input row.',
+                decision_index: decision.decisionIndex,
+                row_index: decision.rowIndex ?? undefined,
+                dataset_id: decision.datasetId,
+                dataset_version: decision.datasetVersion,
+            });
+            continue;
+        }
+        const row = matches[0];
+        if (decision.categoryType === 'location') {
+            const code = locationCodeFromPath(decision.path);
+            const targetMatches = resolveLocationTarget(row, decision);
+            if (!code || targetMatches.length !== 1) {
+                blockers.push({
+                    code: targetMatches.length === 0 ? 'location_target_not_found' : 'location_target_ambiguous',
+                    message: targetMatches.length === 0
+                        ? 'Location decision did not match a location field in the input row.'
+                        : 'Location decision matched more than one location field; provide target_path.',
+                    decision_index: decision.decisionIndex,
+                    row_index: row.index,
+                    dataset_id: row.id,
+                    dataset_version: row.version,
+                });
+                continue;
+            }
+            const target = targetMatches[0];
+            const previous = target.value;
+            target.parent[target.key] = code;
+            evidence.push({
+                decision_index: decision.decisionIndex,
+                row_index: row.index,
+                dataset_id: row.id,
+                dataset_version: row.version,
+                category_type: decision.categoryType,
+                target_path: target.path,
+                previous_location: previous,
+                applied_location: code,
+                applied_location_path: cloneJson(decision.path),
+                basis: decision.basis,
+                evidence: decision.evidence,
+            });
+            continue;
+        }
+        const previous = currentClassification(row, decision.categoryType);
+        if (!setClassification(row, decision.categoryType, decision.path)) {
+            blockers.push({
+                code: 'classification_container_missing',
+                message: 'Input row does not contain a supported classification container for this type.',
+                decision_index: decision.decisionIndex,
+                row_index: row.index,
+                dataset_id: row.id,
+                dataset_version: row.version,
+            });
+            continue;
+        }
+        evidence.push({
+            decision_index: decision.decisionIndex,
+            row_index: row.index,
+            dataset_id: row.id,
+            dataset_version: row.version,
+            category_type: decision.categoryType,
+            previous_classification: previous,
+            applied_classification: cloneJson(decision.path),
+            basis: decision.basis,
+            evidence: decision.evidence,
+        });
+    }
+    const outDir = options.outDir
+        ? path.resolve(options.outDir)
+        : path.dirname(path.resolve(options.outPath));
+    const evidencePath = path.join(outDir, 'outputs', 'classification-apply-evidence.jsonl');
+    const reportPath = path.join(outDir, 'outputs', 'classification-apply-report.json');
+    writeJsonLinesArtifact(options.outPath, rows.map((row) => row.payload));
+    writeJsonLinesArtifact(evidencePath, evidence);
+    const report = {
+        schema_version: 1,
+        generated_at_utc: (options.now ?? new Date()).toISOString(),
+        status: blockers.length > 0 ? 'blocked' : 'completed',
+        command: 'dataset classification apply',
+        input_path: path.resolve(options.inputPath),
+        decisions_path: path.resolve(options.decisionsPath),
+        out_path: path.resolve(options.outPath),
+        default_category_type: fallbackType,
+        counts: {
+            rows: rows.length,
+            decisions: rawDecisions.length,
+            applied: evidence.length,
+            blockers: blockers.length,
+        },
+        blockers,
+        files: {
+            classified_rows: path.resolve(options.outPath),
+            evidence: evidencePath,
+            report: reportPath,
+        },
+    };
+    writeJsonArtifact(reportPath, report);
+    return report;
+}
+export const __testInternals = {
+    buildNavigator,
+    classCode,
+    classificationContainer,
+    collectEntriesFromNode,
+    collectLocationRefKeysFromSchema,
+    collectLocationTargets,
+    constText,
+    currentClassification,
+    decisionMatchesRow,
+    decisionTargetPath,
+    isJsonSchemaFileName,
+    lastSchemaPropertyName,
+    loadEntries,
+    locationCodeFromPath,
+    locationTargetStringValue,
+    locationTargetKeys,
+    maybeWriteReport,
+    navigatorFor,
+    normalizeDecision,
+    normalizeDecisionType,
+    normalizePathFromClasses,
+    normalizePathFromDecision,
+    normalizeStructuredDecisions,
+    normalizeTargetPath,
+    normalizeType,
+    pathForCode,
+    prepareRows,
+    readDecisions,
+    resolveLocationTarget,
+    schemasDir,
+    setClassification,
+    toPathEntry,
+};
+//# sourceMappingURL=dataset-classification.js.map