@a16njs/engine 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -7,10 +7,25 @@ export interface ConversionOptions {
     source: string;
     /** Target plugin ID */
     target: string;
-    /** Project root directory */
+    /** Project root directory (used as default for both source and target) */
     root: string;
     /** If true, only discover without writing */
     dryRun?: boolean;
+    /**
+     * Override root directory for discovery (reading).
+     * When set, discover() uses this instead of `root`.
+     */
+    sourceRoot?: string;
+    /**
+     * Override root directory for emission (writing).
+     * When set, emit() uses this instead of `root`.
+     */
+    targetRoot?: string;
+    /**
+     * If true, rewrite file path references in content so they point
+     * to the target-format paths instead of source-format paths.
+     */
+    rewritePathRefs?: boolean;
 }
 /**
  * Git-ignore change information.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,OAAO,EACP,WAAW,EACX,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAExB;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,8BAA8B;IAC9B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,2CAA2C;IAC3C,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,mDAAmD;IACnD,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;IACrC,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,MAAM,EAAE,SAAS,GAAG,WAAW,CAAC;CACjC;AAED;;;GAGG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAsC;IAErD;;;OAGG;gBACS,OAAO,GAAE,UAAU,EAAO;IAMtC;;;OAGG;IACH,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAIxC;;;OAGG;IACH,WAAW,IAAI,UAAU,EAAE;IAS3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI7C;;;;;OAKG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAQxE;;;;OAIG;IACG,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;CA0BrE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,OAAO,EACP,WAAW,EACX,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAsBxB;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,8BAA8B;IAC9B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,2CAA2C;IAC3C,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,mDAAmD;IACnD,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;IACrC,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,MAAM,EAAE,SAAS,GAAG,WAAW,CAAC;CACjC;AAED;;;GAGG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAsC;IAErD;;;OAGG;gBACS,OAAO,GAAE,UAAU,EAAO;IAMtC;;;OAGG;IACH,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAIxC;;;OAGG;IACH,WAAW,IAAI,UAAU,EAAE;IAS3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI7C;;;;;OAKG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAQxE;;;;OAIG;IACG,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAmFrE"}

package/dist/index.js

@@ -1,3 +1,22 @@
+import { buildMapping, rewriteContent, detectOrphans } from './path-rewriter.js';
+/**
+ * Well-known directory prefixes and file extensions for each plugin.
+ * Used by detectOrphans() to identify source-format path references.
+ */
+const PLUGIN_PATH_PATTERNS = {
+    cursor: {
+        prefixes: ['.cursor/rules/', '.cursor/skills/', '.cursor/commands/'],
+        extensions: ['.mdc', '.md'],
+    },
+    claude: {
+        prefixes: ['.claude/rules/', '.claude/skills/'],
+        extensions: ['.md'],
+    },
+    a16n: {
+        prefixes: ['.a16n/'],
+        extensions: ['.md', '.json'],
+    },
+};
 /**
  * The a16n conversion engine.
  * Orchestrates plugins to discover and emit agent customizations.
@@ -67,16 +86,55 @@ export class A16nEngine {
         if (!targetPlugin) {
             throw new Error(`Unknown target: ${options.target}`);
         }
+        // Resolve split roots: sourceRoot for discover, targetRoot for emit
+        const effectiveSourceRoot = options.sourceRoot ?? options.root;
+        const effectiveTargetRoot = options.targetRoot ?? options.root;
         // Discover from source
-        const discovery = await sourcePlugin.discover(options.root);
-        // Emit to target (pass dryRun to calculate what would be written)
-        const emission = await targetPlugin.emit(discovery.items, options.root, {
+        const discovery = await sourcePlugin.discover(effectiveSourceRoot);
+        const allWarnings = [...discovery.warnings];
+        if (options.rewritePathRefs && discovery.items.length > 0) {
+            // Two-pass emit approach:
+            // Pass 1: Dry-run emit to get target paths for building the mapping
+            const dryEmission = await targetPlugin.emit(discovery.items, effectiveTargetRoot, {
+                dryRun: true,
+            });
+            allWarnings.push(...dryEmission.warnings);
+            // Build source→target path mapping from the dry-run results
+            const mapping = buildMapping(discovery.items, dryEmission.written, effectiveSourceRoot, effectiveTargetRoot);
+            // Rewrite content in discovered items
+            const rewriteResult = rewriteContent(discovery.items, mapping);
+            // Detect orphan references
+            const sourcePatterns = PLUGIN_PATH_PATTERNS[options.source];
+            if (sourcePatterns) {
+                const orphanWarnings = detectOrphans(rewriteResult.items, mapping, sourcePatterns.prefixes, sourcePatterns.extensions);
+                allWarnings.push(...orphanWarnings);
+            }
+            // Pass 2: Real emit with rewritten items
+            const emission = await targetPlugin.emit(rewriteResult.items, effectiveTargetRoot, {
+                dryRun: options.dryRun,
+            });
+            // Deduplicate: add only emission warnings not already present from dry-run
+            const existingMessages = new Set(allWarnings.map((w) => w.message));
+            for (const w of emission.warnings) {
+                if (!existingMessages.has(w.message)) {
+                    allWarnings.push(w);
+                }
+            }
+            return {
+                discovered: discovery.items,
+                written: emission.written,
+                warnings: allWarnings,
+                unsupported: emission.unsupported,
+            };
+        }
+        // Standard single-pass emit (no rewriting)
+        const emission = await targetPlugin.emit(discovery.items, effectiveTargetRoot, {
             dryRun: options.dryRun,
         });
         return {
             discovered: discovery.items,
             written: emission.written,
-            warnings: [...discovery.warnings, ...emission.warnings],
+            warnings: [...allWarnings, ...emission.warnings],
             unsupported: emission.unsupported,
         };
     }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA6DA;;;GAGG;AACH,MAAM,OAAO,UAAU;IACb,OAAO,GAA4B,IAAI,GAAG,EAAE,CAAC;IAErD;;;OAGG;IACH,YAAY,UAAwB,EAAE;QACpC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,cAAc,CAAC,MAAkB;QAC/B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAED;;;OAGG;IACH,WAAW;QACT,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACnD,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,MAAM,EAAE,SAAkB;SAC3B,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,EAAU;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,CAAC,QAAgB,EAAE,IAAY;QAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,OAA0B;QACtC,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACpD,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEpD,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,mBAAmB,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,mBAAmB,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACvD,CAAC;QAED,uBAAuB;QACvB,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAE5D,kEAAkE;QAClE,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,EAAE;YACtE,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;QAEH,OAAO;YACL,UAAU,EAAE,SAAS,CAAC,KAAK;YAC3B,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,QAAQ,EAAE,CAAC,GAAG,SAAS,CAAC,QAAQ,EAAE,GAAG,QAAQ,CAAC,QAAQ,CAAC;YACvD,WAAW,EAAE,QAAQ,CAAC,WAAW;SAClC,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/path-rewriter.d.ts

@@ -0,0 +1,68 @@
+import type { AgentCustomization, Warning } from '@a16njs/models';
+import type { WrittenFile } from '@a16njs/models';
+/**
+ * A mapping from source-relative paths to target-relative paths.
+ * Used to rewrite path references in content during format conversion.
+ */
+export type PathMapping = Map<string, string>;
+/**
+ * Result of a path rewriting operation.
+ */
+export interface RewriteResult {
+    /** The items with rewritten content (cloned; originals are not mutated) */
+    items: AgentCustomization[];
+    /** Count of replacements made across all items */
+    replacementCount: number;
+}
+/**
+ * Build a mapping from source-relative paths to target-relative paths.
+ *
+ * Given the discovered items (with sourcePaths relative to sourceRoot)
+ * and the written files (with absolute paths under targetRoot), produces
+ * a Map where keys are source-relative paths and values are target-relative paths.
+ *
+ * The mapping is derived from the `sourceItems` array on each WrittenFile,
+ * which links each output file back to the source AgentCustomization(s) that
+ * produced it. This handles merges, extension changes, and directory flattening
+ * naturally because the mapping is derived from actual emit output.
+ *
+ * @param _discovered - Items discovered from the source plugin (unused directly; mapping comes from written.sourceItems)
+ * @param written - Files written (or planned) by the target plugin
+ * @param _sourceRoot - Root directory used for discovery (unused; sourcePaths are already relative)
+ * @param targetRoot - Root directory used for emission
+ * @returns A map of source-relative path to target-relative path
+ */
+export declare function buildMapping(_discovered: AgentCustomization[], written: WrittenFile[], _sourceRoot: string, targetRoot: string): PathMapping;
+/**
+ * Rewrite file path references in item content.
+ *
+ * For each item, every occurrence of a mapped source path in the content
+ * is replaced with the corresponding target path. Replacements are applied
+ * longest-first to prevent partial match corruption (e.g., replacing
+ * "foo/bar.mdc.bak" before "foo/bar.mdc").
+ *
+ * Items are cloned before modification; originals are not mutated.
+ *
+ * @param items - The items whose content should be rewritten
+ * @param mapping - The source-to-target path mapping
+ * @returns Cloned items with rewritten content and replacement count
+ */
+export declare function rewriteContent(items: AgentCustomization[], mapping: PathMapping): RewriteResult;
+/**
+ * Detect orphan path references in item content.
+ *
+ * An "orphan" is a string in content that looks like it could be a
+ * source-format file path (matches known source plugin path prefixes
+ * and file extensions) but is NOT present in the mapping (i.e., it
+ * wasn't converted).
+ *
+ * @param items - The items to scan for orphan references
+ * @param mapping - The source-to-target path mapping
+ * @param sourcePluginPrefixes - Known directory prefixes for the source format
+ *   (e.g., ['.cursor/rules/', '.cursor/skills/'] for cursor plugin)
+ * @param sourceExtensions - Known file extensions for the source format
+ *   (e.g., ['.mdc', '.md'] for cursor plugin)
+ * @returns Warnings about orphan references found
+ */
+export declare function detectOrphans(items: AgentCustomization[], mapping: PathMapping, sourcePluginPrefixes: string[], sourceExtensions: string[]): Warning[];
+//# sourceMappingURL=path-rewriter.d.ts.map

package/dist/path-rewriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-rewriter.d.ts","sourceRoot":"","sources":["../src/path-rewriter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAElE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,kDAAkD;IAClD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,kBAAkB,EAAE,EACjC,OAAO,EAAE,WAAW,EAAE,EACtB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,WAAW,CAoBb;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,kBAAkB,EAAE,EAC3B,OAAO,EAAE,WAAW,GACnB,aAAa,CAgDf;AASD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,kBAAkB,EAAE,EAC3B,OAAO,EAAE,WAAW,EACpB,oBAAoB,EAAE,MAAM,EAAE,EAC9B,gBAAgB,EAAE,MAAM,EAAE,GACzB,OAAO,EAAE,CAmCX"}

package/dist/path-rewriter.js

@@ -0,0 +1,144 @@
+import * as path from 'path';
+import { WarningCode } from '@a16njs/models';
+/**
+ * Build a mapping from source-relative paths to target-relative paths.
+ *
+ * Given the discovered items (with sourcePaths relative to sourceRoot)
+ * and the written files (with absolute paths under targetRoot), produces
+ * a Map where keys are source-relative paths and values are target-relative paths.
+ *
+ * The mapping is derived from the `sourceItems` array on each WrittenFile,
+ * which links each output file back to the source AgentCustomization(s) that
+ * produced it. This handles merges, extension changes, and directory flattening
+ * naturally because the mapping is derived from actual emit output.
+ *
+ * @param _discovered - Items discovered from the source plugin (unused directly; mapping comes from written.sourceItems)
+ * @param written - Files written (or planned) by the target plugin
+ * @param _sourceRoot - Root directory used for discovery (unused; sourcePaths are already relative)
+ * @param targetRoot - Root directory used for emission
+ * @returns A map of source-relative path to target-relative path
+ */
+export function buildMapping(_discovered, written, _sourceRoot, targetRoot) {
+    const mapping = new Map();
+    for (const file of written) {
+        // Compute target-relative path using POSIX separators for consistency
+        const targetRelative = path.relative(targetRoot, file.path).split(path.sep).join('/');
+        // Map each source item's sourcePath to this target path
+        if (file.sourceItems) {
+            for (const sourceItem of file.sourceItems) {
+                if (sourceItem.sourcePath) {
+                    // Normalize to POSIX separators
+                    const normalizedSourcePath = sourceItem.sourcePath.split(path.sep).join('/');
+                    mapping.set(normalizedSourcePath, targetRelative);
+                }
+            }
+        }
+    }
+    return mapping;
+}
+/**
+ * Rewrite file path references in item content.
+ *
+ * For each item, every occurrence of a mapped source path in the content
+ * is replaced with the corresponding target path. Replacements are applied
+ * longest-first to prevent partial match corruption (e.g., replacing
+ * "foo/bar.mdc.bak" before "foo/bar.mdc").
+ *
+ * Items are cloned before modification; originals are not mutated.
+ *
+ * @param items - The items whose content should be rewritten
+ * @param mapping - The source-to-target path mapping
+ * @returns Cloned items with rewritten content and replacement count
+ */
+export function rewriteContent(items, mapping) {
+    if (mapping.size === 0) {
+        // No mapping → return clones with no changes
+        return {
+            items: items.map((item) => ({ ...item })),
+            replacementCount: 0,
+        };
+    }
+    // Sort replacements longest-first to prevent partial match corruption
+    const sortedEntries = Array.from(mapping.entries()).sort((a, b) => b[0].length - a[0].length);
+    let totalReplacements = 0;
+    const rewrittenItems = items.map((item) => {
+        // Clone the item (shallow clone is sufficient since we only modify content)
+        const clone = { ...item };
+        let content = clone.content;
+        // NOTE: Replacements are applied sequentially. This is safe because source
+        // and target paths use different plugin directory prefixes, so a target path
+        // won't match a subsequent source key.
+        for (const [sourcePath, targetPath] of sortedEntries) {
+            // Count occurrences before replacement
+            let count = 0;
+            let idx = 0;
+            while ((idx = content.indexOf(sourcePath, idx)) !== -1) {
+                count++;
+                idx += sourcePath.length;
+            }
+            if (count > 0) {
+                // Use split+join for exact string replacement (no regex escaping needed)
+                content = content.split(sourcePath).join(targetPath);
+                totalReplacements += count;
+            }
+        }
+        clone.content = content;
+        return clone;
+    });
+    return {
+        items: rewrittenItems,
+        replacementCount: totalReplacements,
+    };
+}
+/**
+ * Escape a string for use in a RegExp.
+ */
+function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Detect orphan path references in item content.
+ *
+ * An "orphan" is a string in content that looks like it could be a
+ * source-format file path (matches known source plugin path prefixes
+ * and file extensions) but is NOT present in the mapping (i.e., it
+ * wasn't converted).
+ *
+ * @param items - The items to scan for orphan references
+ * @param mapping - The source-to-target path mapping
+ * @param sourcePluginPrefixes - Known directory prefixes for the source format
+ *   (e.g., ['.cursor/rules/', '.cursor/skills/'] for cursor plugin)
+ * @param sourceExtensions - Known file extensions for the source format
+ *   (e.g., ['.mdc', '.md'] for cursor plugin)
+ * @returns Warnings about orphan references found
+ */
+export function detectOrphans(items, mapping, sourcePluginPrefixes, sourceExtensions) {
+    if (sourcePluginPrefixes.length === 0 || sourceExtensions.length === 0) {
+        return [];
+    }
+    const warnings = [];
+    const mappedPaths = new Set(mapping.keys());
+    const seen = new Set();
+    // Build a regex that matches: <prefix><non-whitespace-path><extension>
+    // e.g., .cursor/rules/some-file.mdc
+    const escapedPrefixes = sourcePluginPrefixes.map(escapeRegExp).join('|');
+    const escapedExtensions = sourceExtensions.map(escapeRegExp).join('|');
+    const pattern = new RegExp(`(?:${escapedPrefixes})[^\\s)\\]}>,"']+(?:${escapedExtensions})`, 'g');
+    for (const item of items) {
+        const matches = item.content.matchAll(pattern);
+        for (const match of matches) {
+            const foundPath = match[0];
+            const key = `${item.sourcePath ?? ''}::${foundPath}`;
+            if (!mappedPaths.has(foundPath) && !seen.has(key)) {
+                seen.add(key);
+                warnings.push({
+                    code: WarningCode.OrphanPathRef,
+                    message: `Orphan path reference: '${foundPath}' is not in the conversion set`,
+                    sources: item.sourcePath ? [item.sourcePath] : undefined,
+                });
+            }
+        }
+    }
+    return warnings;
+}
+//# sourceMappingURL=path-rewriter.js.map

package/dist/path-rewriter.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a16njs/engine",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Conversion engine for a16n",
   "license": "AGPL-3.0",
   "author": "Texarkanine",
@@ -31,14 +31,14 @@
     "dist"
   ],
   "dependencies": {
-    "@a16njs/models": "0.6.0"
+    "@a16njs/models": "0.9.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.4.0",
     "vitest": "^2.0.0",
-    "@a16njs/plugin-cursor": "0.7.0",
-    "@a16njs/plugin-claude": "0.7.0"
+    "@a16njs/plugin-cursor": "0.9.0",
+    "@a16njs/plugin-claude": "0.9.0"
   },
   "scripts": {
     "build": "tsc",