mewkit 1.13.0 → 1.14.0

package/dist/migrate/validation/migrate-conversion-report.js

@@ -0,0 +1,105 @@
+// Builds the pre-install conversion report: converts every planned item
+// in-memory (plus portable skill markdown), aggregates classifier decisions,
+// and runs the unresolved-reference scanner. Console/in-memory only — nothing
+// here writes into the target project.
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { convertItem } from "../converters/index.js";
+import { providers } from "../provider-registry.js";
+import { combineIntegrityIndexes, createReferenceIntegrityIndex, rewriteSourceReferences, } from "../references/fence-aware-reference-rewriter.js";
+import { scanUnresolvedReferences } from "./unresolved-reference-scanner.js";
+const TYPE_KEY = {
+    agent: "agents",
+    command: "commands",
+    skill: "skills",
+    config: "config",
+    rules: "rules",
+    hooks: "hooks",
+};
+function collectMarkdownFiles(dir) {
+    const files = [];
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory())
+            files.push(...collectMarkdownFiles(full));
+        else if (entry.toLowerCase().endsWith(".md"))
+            files.push(full);
+    }
+    return files;
+}
+export function buildConversionReport(input) {
+    const outputs = [];
+    const occurrences = [];
+    const conversionWarnings = new Set();
+    const budgetByTarget = new Map();
+    for (const action of input.actions) {
+        if (action.action !== "install" && action.action !== "update" && action.action !== "conflict")
+            continue;
+        const provider = action.provider;
+        const pathConfig = providers[provider]?.[TYPE_KEY[action.type]];
+        if (!pathConfig)
+            continue;
+        const item = input.itemsByType[action.type]?.find((i) => i.name === action.item);
+        if (!item)
+            continue;
+        const conversion = convertItem(item, pathConfig.format, provider, { migratedRefs: input.migratedRefs });
+        if (conversion.error)
+            continue;
+        const file = `${provider}/${action.type}/${action.item}`;
+        outputs.push({ file, content: conversion.content, occurrences: conversion.occurrences ?? [] });
+        occurrences.push(...(conversion.occurrences ?? []).map((o) => ({ ...o, file: o.file || file })));
+        for (const warning of conversion.warnings)
+            conversionWarnings.add(warning);
+        if (pathConfig.writeStrategy === "merge-single" && pathConfig.totalCharLimit) {
+            const key = `${provider}:${pathConfig.projectPath ?? pathConfig.globalPath ?? ""}`;
+            const entry = budgetByTarget.get(key) ?? { bytes: 0, budget: pathConfig.totalCharLimit };
+            entry.bytes += Buffer.byteLength(conversion.content, "utf-8");
+            budgetByTarget.set(key, entry);
+        }
+    }
+    for (const [provider, skills] of input.skillsByProvider) {
+        if (!providers[provider]?.skills)
+            continue;
+        for (const skill of skills) {
+            const selfIndex = createReferenceIntegrityIndex([`.claude/skills/${skill.dirName}/`]);
+            const index = combineIntegrityIndexes(selfIndex, input.migratedRefs);
+            let files;
+            try {
+                files = collectMarkdownFiles(skill.sourcePath);
+            }
+            catch {
+                continue;
+            }
+            for (const filePath of files) {
+                const relName = relative(skill.sourcePath, filePath);
+                const file = `${provider}/skill/${skill.name}/${relName}`;
+                let content;
+                try {
+                    content = readFileSync(filePath, "utf-8");
+                }
+                catch {
+                    continue;
+                }
+                const rewritten = rewriteSourceReferences(content, { provider, file, migratedRefs: index });
+                outputs.push({ file, content: rewritten.content, occurrences: rewritten.occurrences });
+                occurrences.push(...rewritten.occurrences);
+            }
+        }
+    }
+    const warnedReferences = occurrences
+        .filter((o) => o.decision === "preserve-warn")
+        .map((o) => `${o.file}:${o.line} — ${o.original}${o.reason ? ` (${o.reason})` : ""}`);
+    const budgetLines = Array.from(budgetByTarget.entries()).map(([key, { bytes, budget }]) => {
+        const status = bytes > budget ? "OVER budget — the runtime truncates at the cap" : "within budget";
+        return `${key}: projected ~${bytes} B of ${budget} B (${status})`;
+    });
+    const findings = scanUnresolvedReferences(outputs);
+    const validationErrors = findings.map((f) => `${f.file}:${f.line} — ${f.message}`);
+    return {
+        warnedReferences,
+        conversionWarnings: Array.from(conversionWarnings),
+        budgetLines,
+        validationErrors,
+    };
+}
+//# sourceMappingURL=migrate-conversion-report.js.map

package/dist/migrate/validation/migrate-conversion-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-conversion-report.js","sourceRoot":"","sources":["../../../src/migrate/validation/migrate-conversion-report.ts"],"names":[],"mappings":"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"}

package/dist/migrate/validation/unresolved-reference-scanner.d.ts

@@ -0,0 +1,18 @@
+import type { ReferenceOccurrence } from "../references/reference-types.js";
+export interface ScannedOutput {
+    /** Display name for the output (e.g. "codex/config/CLAUDE" or a file path) */
+    file: string;
+    content: string;
+    occurrences: ReferenceOccurrence[];
+}
+export interface ValidationFinding {
+    severity: "error" | "warning";
+    file: string;
+    line: number;
+    reference: string;
+    message: string;
+}
+/** True when a surviving source reference is covered by a classifier decision. */
+export declare function isExplainedReference(reference: string, occurrences: ReferenceOccurrence[]): boolean;
+export declare function scanUnresolvedReferences(outputs: ScannedOutput[]): ValidationFinding[];
+//# sourceMappingURL=unresolved-reference-scanner.d.ts.map

package/dist/migrate/validation/unresolved-reference-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unresolved-reference-scanner.d.ts","sourceRoot":"","sources":["../../../src/migrate/validation/unresolved-reference-scanner.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAE5E,MAAM,WAAW,aAAa;IAC7B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,mBAAmB,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CAChB;AAUD,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,mBAAmB,EAAE,GAAG,OAAO,CASnG;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,iBAAiB,EAAE,CAoBtF"}

package/dist/migrate/validation/unresolved-reference-scanner.js

@@ -0,0 +1,47 @@
+// Post-conversion invariant check: every source reference surviving in
+// generated output must be explained by a classifier decision (preserve,
+// preserve-warn, or a rewrite whose target legitimately still matches the
+// source pattern). An unexplained survivor means the rewriter missed a case —
+// that is an internal error, not a user-content warning.
+import { sourceReferencePattern } from "../references/reference-target-registry.js";
+function lineNumberAt(content, offset) {
+    let line = 1;
+    for (let i = 0; i < offset && i < content.length; i++) {
+        if (content[i] === "\n")
+            line++;
+    }
+    return line;
+}
+/** True when a surviving source reference is covered by a classifier decision. */
+export function isExplainedReference(reference, occurrences) {
+    return occurrences.some((occurrence) => {
+        if (occurrence.decision === "preserve" || occurrence.decision === "preserve-warn") {
+            return occurrence.original.toLowerCase() === reference.toLowerCase();
+        }
+        // A rewrite target can itself match the source pattern (e.g. a provider
+        // that reads skills from the source tree) — that survivor is legitimate.
+        return occurrence.rewrittenTo?.toLowerCase().includes(reference.toLowerCase()) ?? false;
+    });
+}
+export function scanUnresolvedReferences(outputs) {
+    const findings = [];
+    for (const output of outputs) {
+        const pattern = sourceReferencePattern();
+        for (const match of output.content.matchAll(pattern)) {
+            if (match.index === undefined)
+                continue;
+            const reference = match[0];
+            if (isExplainedReference(reference, output.occurrences))
+                continue;
+            findings.push({
+                severity: "error",
+                file: output.file,
+                line: lineNumberAt(output.content, match.index),
+                reference,
+                message: `unexplained source reference "${reference}" survived conversion — the reference rewriter missed this case`,
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=unresolved-reference-scanner.js.map

package/dist/migrate/validation/unresolved-reference-scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unresolved-reference-scanner.js","sourceRoot":"","sources":["../../../src/migrate/validation/unresolved-reference-scanner.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,yEAAyE;AACzE,0EAA0E;AAC1E,8EAA8E;AAC9E,yDAAyD;AAEzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AAkBpF,SAAS,YAAY,CAAC,OAAe,EAAE,MAAc;IACpD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvD,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI;YAAE,IAAI,EAAE,CAAC;IACjC,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,oBAAoB,CAAC,SAAiB,EAAE,WAAkC;IACzF,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE;QACtC,IAAI,UAAU,CAAC,QAAQ,KAAK,UAAU,IAAI,UAAU,CAAC,QAAQ,KAAK,eAAe,EAAE,CAAC;YACnF,OAAO,UAAU,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC,WAAW,EAAE,CAAC;QACtE,CAAC;QACD,wEAAwE;QACxE,yEAAyE;QACzE,OAAO,UAAU,CAAC,WAAW,EAAE,WAAW,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,IAAI,KAAK,CAAC;IACzF,CAAC,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,OAAwB;IAChE,MAAM,QAAQ,GAAwB,EAAE,CAAC;IAEzC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,sBAAsB,EAAE,CAAC;QACzC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACtD,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;gBAAE,SAAS;YACxC,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YAC3B,IAAI,oBAAoB,CAAC,SAAS,EAAE,MAAM,CAAC,WAAW,CAAC;gBAAE,SAAS;YAClE,QAAQ,CAAC,IAAI,CAAC;gBACb,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC;gBAC/C,SAAS;gBACT,OAAO,EAAE,iCAAiC,SAAS,iEAAiE;aACpH,CAAC,CAAC;QACJ,CAAC;IACF,CAAC;IAED,OAAO,QAAQ,CAAC;AACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mewkit",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "MeowKit CLI — scaffold, upgrade, and manage your AI agent toolkit",
   "type": "module",
   "bin": {