mustflow 2.85.4 → 2.99.0

package/dist/core/import-cycle.js

@@ -0,0 +1,152 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { DEPENDENCY_GRAPH_SCRIPT_REF, inspectDependencyGraph, } from './dependency-graph.js';
+export const IMPORT_CYCLE_PACK_ID = 'code';
+export const IMPORT_CYCLE_SCRIPT_ID = 'import-cycle';
+export const IMPORT_CYCLE_SCRIPT_REF = `${IMPORT_CYCLE_PACK_ID}/${IMPORT_CYCLE_SCRIPT_ID}`;
+const DEFAULT_MAX_DEPTH = 20;
+const DEFAULT_MAX_CYCLES = 50;
+const MAX_ISSUES = 50;
+function sha256Tagged(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+function cycleId(paths) {
+    return `cycle:${createHash('sha256').update(paths.join('\0')).digest('hex').slice(0, 12)}`;
+}
+function edgeKey(sourcePath, targetPath) {
+    return `${sourcePath}\0${targetPath}`;
+}
+function buildEdgeIndex(edges) {
+    const index = new Map();
+    for (const edge of edges) {
+        const key = edgeKey(edge.source_path, edge.target_path);
+        const existing = index.get(key) ?? [];
+        existing.push(edge);
+        index.set(key, existing);
+    }
+    for (const indexedEdges of index.values()) {
+        indexedEdges.sort((left, right) => left.line - right.line ||
+            left.kind.localeCompare(right.kind) ||
+            left.specifier.localeCompare(right.specifier));
+    }
+    return index;
+}
+function importCycleEdges(cyclePaths, edgeIndex) {
+    const edges = [];
+    let index = 0;
+    while (index < cyclePaths.length - 1) {
+        const sourcePath = cyclePaths[index];
+        const targetPath = cyclePaths[index + 1];
+        if (!sourcePath || !targetPath) {
+            index += 1;
+            continue;
+        }
+        const [edge] = edgeIndex.get(edgeKey(sourcePath, targetPath)) ?? [];
+        if (edge) {
+            edges.push({
+                source_path: edge.source_path,
+                target_path: edge.target_path,
+                specifier: edge.specifier,
+                line: edge.line,
+                kind: edge.kind,
+            });
+        }
+        index += 1;
+    }
+    return edges;
+}
+function makeFinding(code, severity, pathValue, message, cycle_id) {
+    return cycle_id
+        ? { code, severity, path: pathValue, message, cycle_id }
+        : { code, severity, path: pathValue, message };
+}
+function normalizeGraphFinding(finding) {
+    return {
+        code: finding.code,
+        severity: finding.severity,
+        path: finding.path,
+        message: finding.message,
+    };
+}
+function pushIssue(issues, issue) {
+    if (issues.length < MAX_ISSUES) {
+        issues.push(issue);
+    }
+}
+function importCycleStatus(graphStatus, cycles, findings) {
+    if (graphStatus === 'error') {
+        return 'error';
+    }
+    return cycles.length > 0 || findings.length > 0 ? 'failed' : 'passed';
+}
+function createInputHash(policy, graph, cycles, findings, issues) {
+    return sha256Tagged(JSON.stringify({
+        policy,
+        graph_input_hash: graph.input_hash,
+        targets: graph.targets,
+        cycles: cycles.map((cycle) => ({ cycle_id: cycle.cycle_id, paths: cycle.paths })),
+        findings: findings.map((finding) => ({ code: finding.code, path: finding.path, cycle_id: finding.cycle_id })),
+        issues,
+    }));
+}
+export function inspectImportCycles(projectRoot, options) {
+    const root = path.resolve(projectRoot);
+    const graph = inspectDependencyGraph(root, {
+        paths: options.paths,
+        maxFiles: options.maxFiles,
+        maxFileBytes: options.maxFileBytes,
+        maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH,
+        maxNodes: options.maxNodes,
+        maxEdges: options.maxEdges,
+    });
+    const policy = {
+        ...graph.policy,
+        max_cycles: options.maxCycles ?? DEFAULT_MAX_CYCLES,
+    };
+    const edgeIndex = buildEdgeIndex(graph.edges);
+    const cycles = graph.cycles.slice(0, policy.max_cycles).map((cyclePaths) => ({
+        cycle_id: cycleId(cyclePaths),
+        path_count: Math.max(0, cyclePaths.length - 1),
+        paths: cyclePaths,
+        edges: importCycleEdges(cyclePaths, edgeIndex),
+    }));
+    const issues = [...graph.issues];
+    const findings = graph.findings.map(normalizeGraphFinding);
+    for (const cycle of cycles) {
+        const [firstPath] = cycle.paths;
+        findings.push(makeFinding('import_cycle_detected', 'high', firstPath ?? '.', `Import cycle detected: ${cycle.paths.join(' -> ')}`, cycle.cycle_id));
+    }
+    if (graph.cycles.length > cycles.length) {
+        const message = `Import cycle scan found more than ${policy.max_cycles} cycles; remaining cycles were skipped.`;
+        pushIssue(issues, message);
+        findings.push(makeFinding('import_cycle_max_cycles_exceeded', 'medium', '.', message));
+    }
+    const status = importCycleStatus(graph.status, cycles, findings);
+    const truncated = graph.truncated || graph.cycles.length > cycles.length;
+    return {
+        schema_version: '1',
+        command: 'script-pack',
+        pack_id: IMPORT_CYCLE_PACK_ID,
+        script_id: IMPORT_CYCLE_SCRIPT_ID,
+        script_ref: IMPORT_CYCLE_SCRIPT_REF,
+        action: 'check',
+        status,
+        ok: status === 'passed',
+        mustflow_root: root,
+        policy,
+        input_hash: createInputHash(policy, graph, cycles, findings, issues),
+        targets: graph.targets,
+        graph: {
+            script_ref: DEPENDENCY_GRAPH_SCRIPT_REF,
+            status: graph.status,
+            node_count: graph.nodes.length,
+            edge_count: graph.edges.length,
+            cycle_hint_count: graph.cycles.length,
+            truncated: graph.truncated,
+        },
+        cycles,
+        truncated,
+        findings,
+        issues,
+    };
+}

package/dist/core/public-json-contracts.js

@@ -264,6 +264,23 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
             '--json',
         ],
     },
+    {
+        id: 'import-cycle-report',
+        schemaFile: 'import-cycle-report.schema.json',
+        producer: 'mf script-pack run code/import-cycle check <path...> --json',
+        packaged: true,
+        documented: true,
+        installedCommand: [
+            'mf',
+            'script-pack',
+            'run',
+            'code/import-cycle',
+            'check',
+            'node_modules/mustflow/dist/cli/index.js',
+            '--json',
+        ],
+        expectedExitCodes: [0, 1],
+    },
     {
         id: 'change-impact-report',
         schemaFile: 'change-impact-report.schema.json',
@@ -342,6 +359,42 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         ],
         expectedExitCodes: [0, 1],
     },
+    {
+        id: 'link-integrity-report',
+        schemaFile: 'link-integrity-report.schema.json',
+        producer: 'mf script-pack run docs/link-integrity check [path...] --json',
+        packaged: true,
+        documented: true,
+        installedCommand: [
+            'mf',
+            'script-pack',
+            'run',
+            'docs/link-integrity',
+            'check',
+            'node_modules/mustflow/README.md',
+            'node_modules/mustflow/schemas/README.md',
+            '--json',
+        ],
+        expectedExitCodes: [0, 1],
+    },
+    {
+        id: 'test-performance-report',
+        schemaFile: 'test-performance-report.schema.json',
+        producer: 'mf script-pack run test/performance-report summarize --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'script-pack', 'run', 'test/performance-report', 'summarize', '--json'],
+        expectedExitCodes: [0, 1],
+    },
+    {
+        id: 'test-regression-selector-report',
+        schemaFile: 'test-regression-selector-report.schema.json',
+        producer: 'mf script-pack run test/regression-selector select --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'script-pack', 'run', 'test/regression-selector', 'select', '--json'],
+        expectedExitCodes: [0, 1],
+    },
     {
         id: 'text-budget-report',
         schemaFile: 'text-budget-report.schema.json',
@@ -379,6 +432,69 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         ],
         expectedExitCodes: [0, 1],
     },
+    {
+        id: 'repo-merge-conflict-scan-report',
+        schemaFile: 'repo-merge-conflict-scan-report.schema.json',
+        producer: 'mf script-pack run repo/merge-conflict-scan check [path...] --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'script-pack', 'run', 'repo/merge-conflict-scan', 'check', '--json'],
+        expectedExitCodes: [0, 1],
+    },
+    {
+        id: 'repo-git-ignore-audit-report',
+        schemaFile: 'repo-git-ignore-audit-report.schema.json',
+        producer: 'mf script-pack run repo/git-ignore-audit audit [path...] --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'script-pack', 'run', 'repo/git-ignore-audit', 'audit', 'AGENTS.md', '--json'],
+        expectedExitCodes: [0, 1],
+    },
+    {
+        id: 'repo-manifest-lock-drift-report',
+        schemaFile: 'repo-manifest-lock-drift-report.schema.json',
+        producer: 'mf script-pack run repo/manifest-lock-drift check [path...] --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'script-pack', 'run', 'repo/manifest-lock-drift', 'check', 'AGENTS.md', '--json'],
+        expectedExitCodes: [0, 1],
+    },
+    {
+        id: 'skill-route-audit-report',
+        schemaFile: 'skill-route-audit-report.schema.json',
+        producer: 'mf script-pack run repo/skill-route-audit audit --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'script-pack', 'run', 'repo/skill-route-audit', 'audit', '--json'],
+        expectedExitCodes: [0, 1],
+    },
+    {
+        id: 'repo-version-source-report',
+        schemaFile: 'repo-version-source-report.schema.json',
+        producer: 'mf script-pack run repo/version-source inspect --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'script-pack', 'run', 'repo/version-source', 'inspect', '--json'],
+        expectedExitCodes: [0, 1],
+    },
+    {
+        id: 'repo-approval-gate-report',
+        schemaFile: 'repo-approval-gate-report.schema.json',
+        producer: 'mf script-pack run repo/approval-gate check --action <type> --json',
+        packaged: true,
+        documented: true,
+        installedCommand: [
+            'mf',
+            'script-pack',
+            'run',
+            'repo/approval-gate',
+            'check',
+            '--action',
+            'git_commit',
+            '--json',
+        ],
+        expectedExitCodes: [0, 1],
+    },
     {
         id: 'config-chain-report',
         schemaFile: 'config-chain-report.schema.json',

package/dist/core/repo-approval-gate.js

@@ -0,0 +1,116 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { isRecord, MUSTFLOW_CONFIG_RELATIVE_PATH, readMustflowConfigIfExists, readStringArray, } from './config-loading.js';
+export const REPO_APPROVAL_GATE_PACK_ID = 'repo';
+export const REPO_APPROVAL_GATE_SCRIPT_ID = 'approval-gate';
+export const REPO_APPROVAL_GATE_SCRIPT_REF = `${REPO_APPROVAL_GATE_PACK_ID}/${REPO_APPROVAL_GATE_SCRIPT_ID}`;
+export const REPO_APPROVAL_GATE_POLICY_PATH = MUSTFLOW_CONFIG_RELATIVE_PATH;
+function sha256(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+function uniqueActions(actions) {
+    const normalized = [];
+    const seen = new Set();
+    for (const action of actions) {
+        const trimmed = action.trim();
+        if (trimmed.length === 0 || seen.has(trimmed)) {
+            continue;
+        }
+        seen.add(trimmed);
+        normalized.push(trimmed);
+    }
+    return normalized;
+}
+function readApprovalPolicy(projectRoot, issues) {
+    let config;
+    try {
+        config = readMustflowConfigIfExists(projectRoot);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        issues.push(`Could not read ${REPO_APPROVAL_GATE_POLICY_PATH}: ${message}`);
+    }
+    if (!config) {
+        issues.push(`${REPO_APPROVAL_GATE_POLICY_PATH} is missing.`);
+        return { required_for: [], on_required: null };
+    }
+    if (!isRecord(config.approval)) {
+        issues.push(`[approval] in ${REPO_APPROVAL_GATE_POLICY_PATH} must be a TOML table.`);
+        return { required_for: [], on_required: null };
+    }
+    const approval = config.approval;
+    const requiredFor = readStringArray(approval, 'required_for');
+    if (!requiredFor) {
+        issues.push(`[approval].required_for in ${REPO_APPROVAL_GATE_POLICY_PATH} must be a string array.`);
+    }
+    const onRequired = approval.on_required;
+    if (onRequired !== undefined && typeof onRequired !== 'string') {
+        issues.push(`[approval].on_required in ${REPO_APPROVAL_GATE_POLICY_PATH} must be a string.`);
+    }
+    return {
+        required_for: requiredFor ?? [],
+        on_required: typeof onRequired === 'string' ? onRequired : null,
+    };
+}
+function createDecisions(actionTypes, policy) {
+    const required = new Set(policy.required_for);
+    return actionTypes.map((actionType) => {
+        const approvalRequired = required.has(actionType);
+        return {
+            action_type: actionType,
+            approval_required: approvalRequired,
+            policy_source: approvalRequired ? `${REPO_APPROVAL_GATE_POLICY_PATH}#[approval].required_for` : null,
+            reason: approvalRequired
+                ? `Action "${actionType}" is listed in [approval].required_for.`
+                : `Action "${actionType}" is not listed in [approval].required_for.`,
+        };
+    });
+}
+function createFindings(decisions) {
+    return decisions
+        .filter((decision) => decision.approval_required)
+        .map((decision) => ({
+        code: 'approval_required_for_action',
+        severity: 'high',
+        path: REPO_APPROVAL_GATE_POLICY_PATH,
+        message: `Action "${decision.action_type}" requires explicit approval before proceeding.`,
+        json_pointer: '/approval/required_for',
+        metric: null,
+        actual: null,
+        expected: null,
+    }));
+}
+function createInputHash(reportInput) {
+    return sha256(JSON.stringify(reportInput));
+}
+export function checkRepoApprovalGate(projectRoot, actionTypes) {
+    const root = path.resolve(projectRoot);
+    const actions = uniqueActions(actionTypes);
+    const issues = [];
+    const policy = readApprovalPolicy(root, issues);
+    const decisions = issues.length > 0 ? [] : createDecisions(actions, policy);
+    const findings = createFindings(decisions);
+    const approvalRequired = findings.length > 0;
+    const status = issues.length > 0 ? 'error' : approvalRequired ? 'failed' : 'passed';
+    return {
+        schema_version: '1',
+        command: 'script-pack',
+        pack_id: REPO_APPROVAL_GATE_PACK_ID,
+        script_id: REPO_APPROVAL_GATE_SCRIPT_ID,
+        script_ref: REPO_APPROVAL_GATE_SCRIPT_REF,
+        action: 'check',
+        status,
+        ok: status === 'passed',
+        mustflow_root: root,
+        input: {
+            action_types: actions,
+            policy_path: REPO_APPROVAL_GATE_POLICY_PATH,
+        },
+        input_hash: createInputHash({ actionTypes: actions, policy, decisions, findings, issues }),
+        approval_required: approvalRequired,
+        policy,
+        decisions,
+        findings,
+        issues,
+    };
+}