@x-oasis/map-diff-range 0.1.0

package/examples/src/index.css

@@ -0,0 +1,253 @@
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+  background: #f5f5f5;
+  padding: 20px;
+  line-height: 1.6;
+}
+
+.container {
+  max-width: 1600px;
+  margin: 0 auto;
+  background: white;
+  border-radius: 8px;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+  padding: 30px;
+}
+
+h1 {
+  color: #333;
+  margin-bottom: 10px;
+  font-size: 28px;
+}
+
+.subtitle {
+  color: #666;
+  margin-bottom: 30px;
+  font-size: 14px;
+}
+
+.section {
+  margin-bottom: 30px;
+}
+
+.section-title {
+  font-size: 18px;
+  font-weight: 600;
+  color: #333;
+  margin-bottom: 15px;
+  padding-bottom: 10px;
+  border-bottom: 2px solid #e0e0e0;
+}
+
+.file-comparison {
+  display: grid;
+  grid-template-columns: 1fr 1fr 1fr;
+  gap: 20px;
+  margin-bottom: 20px;
+}
+
+.file-panel {
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  overflow: hidden;
+}
+
+.file-header {
+  background: #f8f8f8;
+  padding: 10px 15px;
+  font-weight: 600;
+  color: #555;
+  border-bottom: 1px solid #ddd;
+  font-size: 13px;
+}
+
+.file-content {
+  padding: 15px;
+  font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+  font-size: 13px;
+  line-height: 1.8;
+  white-space: pre-wrap;
+  word-wrap: break-word;
+  max-height: 400px;
+  overflow-y: auto;
+  background: #fff;
+  resize: vertical;
+  min-height: 200px;
+  width: 100%;
+  border: none;
+  outline: none;
+}
+
+.file-content:focus {
+  outline: none;
+}
+
+.controls {
+  display: grid;
+  grid-template-columns: 1fr 1fr auto;
+  gap: 15px;
+  margin-bottom: 20px;
+  align-items: end;
+}
+
+.control-group {
+  display: flex;
+  flex-direction: column;
+}
+
+.control-group label {
+  font-size: 12px;
+  font-weight: 600;
+  color: #555;
+  margin-bottom: 5px;
+}
+
+.control-group input {
+  padding: 10px;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  font-size: 14px;
+}
+
+.control-group input:focus {
+  outline: none;
+  border-color: #4a90e2;
+  box-shadow: 0 0 0 3px rgba(74, 144, 226, 0.1);
+}
+
+button {
+  padding: 10px 20px;
+  background: #4a90e2;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  font-size: 14px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background 0.2s;
+}
+
+button:hover {
+  background: #357abd;
+}
+
+button:active {
+  transform: translateY(1px);
+}
+
+.result-panel {
+  border: 2px solid #4a90e2;
+  border-radius: 4px;
+  padding: 15px;
+  background: #f0f7ff;
+  margin-top: 20px;
+}
+
+.result-title {
+  font-weight: 600;
+  color: #4a90e2;
+  margin-bottom: 10px;
+}
+
+.result-content {
+  font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+  font-size: 13px;
+  line-height: 1.8;
+  white-space: pre-wrap;
+  word-wrap: break-word;
+  background: white;
+  padding: 15px;
+  border-radius: 4px;
+  border: 1px solid #ddd;
+  max-height: 400px;
+  overflow-y: auto;
+}
+
+.info-box {
+  background: #e7f3ff;
+  border-left: 4px solid #4a90e2;
+  padding: 12px;
+  margin-bottom: 20px;
+  border-radius: 4px;
+}
+
+.info-box strong {
+  color: #4a90e2;
+}
+
+.analysis-panel {
+  margin-top: 20px;
+  padding: 15px;
+  background: #f9f9f9;
+  border-radius: 4px;
+  border: 1px solid #ddd;
+}
+
+.analysis-item {
+  margin-bottom: 15px;
+  padding: 10px;
+  background: white;
+  border-radius: 4px;
+  border: 1px solid #e0e0e0;
+}
+
+.analysis-item strong {
+  color: #4a90e2;
+  display: block;
+  margin-bottom: 5px;
+}
+
+.analysis-value {
+  font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+  font-size: 12px;
+  color: #333;
+}
+
+.diff-entry {
+  margin: 5px 0;
+  padding: 5px;
+  border-radius: 3px;
+  font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+  font-size: 12px;
+}
+
+.diff-entry.insert {
+  background: #d4edda;
+  color: #155724;
+}
+
+.diff-entry.delete {
+  background: #f8d7da;
+  color: #721c24;
+}
+
+.diff-entry.equal {
+  background: #f8f9fa;
+  color: #333;
+}
+
+.range-info {
+  display: inline-block;
+  margin: 0 5px;
+  padding: 2px 6px;
+  background: #e7f3ff;
+  border-radius: 3px;
+  font-family: monospace;
+  font-size: 12px;
+  color: #4a90e2;
+}
+
+.error-message {
+  padding: 10px;
+  background: #f8d7da;
+  color: #721c24;
+  border-radius: 4px;
+  margin-top: 10px;
+  border: 1px solid #f5c6cb;
+}

package/examples/src/main.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+import './index.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

package/examples/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".",
+    "paths": {
+      "@x-oasis/map-diff-range": ["../src/index.ts"]
+    }
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}

package/examples/tsconfig.node.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["vite.config.ts"]
+}

package/examples/vite.config.ts

@@ -0,0 +1,30 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+// 如果设置了 GITHUB_PAGES 环境变量，使用仓库名和子路径作为 base 路径
+// 格式: owner/repo-name，我们只需要 repo-name
+// 子路径从 GITHUB_PAGES_PATH 环境变量获取，例如: map-diff-range
+const getBasePath = () => {
+  if (process.env.GITHUB_PAGES === 'true') {
+    const repo = process.env.GITHUB_REPOSITORY || 'red-armor/x-oasis';
+    const repoName = repo.split('/')[1];
+    const subPath = process.env.GITHUB_PAGES_PATH || 'map-diff-range';
+    return `/${repoName}/${subPath}/`;
+  }
+  return '/';
+};
+
+export default defineConfig({
+  base: getBasePath(),
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@x-oasis/map-diff-range': path.resolve(__dirname, '../src/index.ts'),
+    },
+  },
+  server: {
+    port: 3000,
+    open: true,
+  },
+});

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@x-oasis/map-diff-range",
+  "version": "0.1.0",
+  "description": "Range mapping and change analysis tool based on diff-match-patch",
+  "main": "dist/index.js",
+  "typings": "dist/index.d.ts",
+  "module": "dist/map-diff-range.esm.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "tsdx": "^0.14.1"
+  },
+  "dependencies": {
+    "diff-match-patch": "^1.0.5"
+  },
+  "scripts": {
+    "build": "tsdx build --tsconfig tsconfig.build.json",
+    "clean": "rimraf ./dist",
+    "test": "vitest",
+    "compile": "tsc -p tsconfig.build.json"
+  }
+}

package/src/index.ts

@@ -0,0 +1,352 @@
+/**
+ * 基于 diff-match-patch 的 range 映射与变更分析工具
+ * 用于在 originalContent / currentContent / finalContent 之间映射 range，并分析片段级变更
+ *
+ * 参考: https://github.com/red-armor/x-oasis/blob/main/packages/diff/diff-match-patch/src/index.ts#L123
+ */
+
+import { diff_match_patch } from 'diff-match-patch';
+
+/** diff 操作常量，与 diff-match-patch 一致 */
+const DIFF_DELETE = -1;
+const DIFF_INSERT = 1;
+const DIFF_EQUAL = 0;
+
+/** 单端 range，start 含头，end 含尾（substring 语义） */
+export interface Range {
+  start: number;
+  end: number;
+}
+
+/** 片段级变更分析结果 */
+export interface FragmentChangeAnalysis {
+  /** 原始片段内容 */
+  originalFragment: string;
+  /** 最终片段内容 */
+  finalFragment: string;
+  /** 是否完全相同 */
+  equal: boolean;
+  /** 仅删除（无新增） */
+  onlyDeletion: boolean;
+  /** 仅新增（无删除） */
+  onlyInsertion: boolean;
+  /** 既有删除又有新增（替换） */
+  replacement: boolean;
+  /** 语义化描述（简短） */
+  summary: string;
+  /** 详细 diff 条目，便于上层做展示或进一步处理 */
+  diffs: Array<[number, string]>;
+}
+
+/**
+ * 将「新内容」中的 offset range 映射到「旧内容」中的 offset range
+ * 等价于 x-oasis 的 mapCurrentRangeToOriginal：diffs = diff_main(older, newer)，给定 newer 上的 [start,end]，返回 older 上的 [start,end]
+ *
+ * @param olderContent 旧内容（diff 的 text1）
+ * @param newerContent 新内容（diff 的 text2）
+ * @param startOffset 新内容中的 range 起始 offset
+ * @param endOffset 新内容中的 range 结束 offset（不含尾，即 [startOffset, endOffset) 或含尾由调用方约定，此处按 substring 含头含尾）
+ * @returns 旧内容中对应的 range；若越界或无效则返回 { start: 0, end: 0 }
+ */
+export function mapNewerRangeToOlder(
+  olderContent: string,
+  newerContent: string,
+  startOffset: number,
+  endOffset: number
+): Range {
+  const dmp = new diff_match_patch();
+  const diffs = dmp.diff_main(olderContent, newerContent);
+  dmp.diff_cleanupSemantic(diffs);
+
+  let newerOffset = 0;
+  let olderOffset = 0;
+  let olderStart: number | null = null;
+  let olderEnd: number | null = null;
+
+  for (let i = 0; i < diffs.length; i++) {
+    const [op, text] = diffs[i];
+    const len = text.length;
+    const nextDiff = i < diffs.length - 1 ? diffs[i + 1] : null;
+
+    if (op === DIFF_EQUAL) {
+      const rangeStart = newerOffset;
+      const rangeEnd = newerOffset + len;
+
+      if (
+        olderStart === null &&
+        startOffset >= rangeStart &&
+        startOffset < rangeEnd
+      ) {
+        olderStart = olderOffset + (startOffset - rangeStart);
+      }
+      if (
+        olderEnd === null &&
+        endOffset > rangeStart &&
+        endOffset <= rangeEnd
+      ) {
+        const offsetInRange = endOffset - rangeStart;
+        olderEnd = olderOffset + offsetInRange;
+        if (endOffset === rangeEnd && nextDiff && nextDiff[0] === DIFF_DELETE) {
+          olderEnd = olderOffset + len + nextDiff[1].length;
+        }
+      }
+
+      newerOffset += len;
+      olderOffset += len;
+    } else if (op === DIFF_INSERT) {
+      const rangeStart = newerOffset;
+      const rangeEnd = newerOffset + len;
+
+      if (
+        olderStart === null &&
+        startOffset >= rangeStart &&
+        startOffset < rangeEnd
+      ) {
+        olderStart = olderOffset;
+      }
+      if (
+        olderEnd === null &&
+        endOffset > rangeStart &&
+        endOffset <= rangeEnd
+      ) {
+        olderEnd = olderOffset;
+      }
+
+      newerOffset += len;
+    } else if (op === DIFF_DELETE) {
+      if (olderStart === null && startOffset <= newerOffset) {
+        olderStart = olderOffset;
+      }
+      if (olderEnd === null && endOffset <= newerOffset) {
+        olderEnd = endOffset === newerOffset ? olderOffset + len : olderOffset;
+      } else if (olderEnd === null && endOffset === newerOffset) {
+        olderEnd = olderOffset + len;
+      }
+
+      olderOffset += len;
+    }
+
+    if (olderStart !== null && olderEnd !== null) break;
+  }
+
+  if (olderStart === null) olderStart = olderOffset;
+  if (olderEnd === null) olderEnd = olderOffset;
+
+  return { start: olderStart, end: olderEnd };
+}
+
+/**
+ * 将「旧内容」中的 offset range 映射到「新内容」中的 offset range
+ * 与 mapNewerRangeToOlder 对称：diffs = diff_main(older, newer)，给定 older 上的 [start,end]，返回 newer 上的 [start,end]
+ *
+ * @param olderContent 旧内容（diff 的 text1）
+ * @param newerContent 新内容（diff 的 text2）
+ * @param startOffset 旧内容中的 range 起始 offset
+ * @param endOffset 旧内容中的 range 结束 offset
+ * @returns 新内容中对应的 range
+ */
+export function mapOlderRangeToNewer(
+  olderContent: string,
+  newerContent: string,
+  startOffset: number,
+  endOffset: number
+): Range {
+  const dmp = new diff_match_patch();
+  const diffs = dmp.diff_main(olderContent, newerContent);
+  dmp.diff_cleanupSemantic(diffs);
+
+  let olderOffset = 0;
+  let newerOffset = 0;
+  let newerStart: number | null = null;
+  let newerEnd: number | null = null;
+
+  for (let i = 0; i < diffs.length; i++) {
+    const [op, text] = diffs[i];
+    const len = text.length;
+    const nextDiff = i < diffs.length - 1 ? diffs[i + 1] : null;
+
+    if (op === DIFF_EQUAL) {
+      const oldRangeStart = olderOffset;
+      const oldRangeEnd = olderOffset + len;
+
+      if (
+        newerStart === null &&
+        startOffset >= oldRangeStart &&
+        startOffset < oldRangeEnd
+      ) {
+        newerStart = newerOffset + (startOffset - oldRangeStart);
+      }
+      if (
+        newerEnd === null &&
+        endOffset > oldRangeStart &&
+        endOffset <= oldRangeEnd
+      ) {
+        const offsetInRange = endOffset - oldRangeStart;
+        newerEnd = newerOffset + offsetInRange;
+        if (
+          endOffset === oldRangeEnd &&
+          nextDiff &&
+          nextDiff[0] === DIFF_INSERT
+        ) {
+          newerEnd = newerOffset + len + nextDiff[1].length;
+        }
+      }
+
+      olderOffset += len;
+      newerOffset += len;
+    } else if (op === DIFF_INSERT) {
+      newerOffset += len;
+    } else if (op === DIFF_DELETE) {
+      const oldRangeStart = olderOffset;
+      const oldRangeEnd = olderOffset + len;
+
+      if (
+        newerStart === null &&
+        startOffset >= oldRangeStart &&
+        startOffset < oldRangeEnd
+      ) {
+        newerStart = newerOffset;
+      }
+      if (
+        newerEnd === null &&
+        endOffset > oldRangeStart &&
+        endOffset <= oldRangeEnd
+      ) {
+        newerEnd = newerOffset;
+      } else if (newerEnd === null && endOffset <= olderOffset) {
+        newerEnd = newerOffset;
+      }
+
+      olderOffset += len;
+    }
+
+    if (newerStart !== null && newerEnd !== null) break;
+  }
+
+  if (newerStart === null) newerStart = newerOffset;
+  if (newerEnd === null) newerEnd = newerOffset;
+
+  return { start: newerStart, end: newerEnd };
+}
+
+/**
+ * 对比两段片段内容，分析发生的变更类型并生成简短描述
+ *
+ * @param originalFragment 原始片段
+ * @param finalFragment 变更后片段
+ * @returns 变更分析结果
+ */
+export function analyzeFragmentChange(
+  originalFragment: string,
+  finalFragment: string
+): FragmentChangeAnalysis {
+  const dmp = new diff_match_patch();
+  const diffs = dmp.diff_main(originalFragment, finalFragment);
+  dmp.diff_cleanupSemantic(diffs);
+
+  const hasDelete = diffs.some(([op]) => op === DIFF_DELETE);
+  const hasInsert = diffs.some(([op]) => op === DIFF_INSERT);
+  const equal = !hasDelete && !hasInsert;
+  const onlyDeletion = hasDelete && !hasInsert;
+  const onlyInsertion = !hasDelete && hasInsert;
+  const replacement = hasDelete && hasInsert;
+
+  let summary: string;
+  if (equal) {
+    summary = '无变更';
+  } else if (onlyDeletion) {
+    const deleted = diffs
+      .filter(([op]) => op === DIFF_DELETE)
+      .map(([, text]) => text)
+      .join('');
+    summary = `删除: ${formatSnippet(deleted)}`;
+  } else if (onlyInsertion) {
+    const inserted = diffs
+      .filter(([op]) => op === DIFF_INSERT)
+      .map(([, text]) => text)
+      .join('');
+    summary = `新增: ${formatSnippet(inserted)}`;
+  } else {
+    const deleted = diffs
+      .filter(([op]) => op === DIFF_DELETE)
+      .map(([, text]) => text)
+      .join('');
+    const inserted = diffs
+      .filter(([op]) => op === DIFF_INSERT)
+      .map(([, text]) => text)
+      .join('');
+    summary = `替换: ${formatSnippet(deleted)} → ${formatSnippet(inserted)}`;
+  }
+
+  return {
+    originalFragment,
+    finalFragment,
+    equal,
+    onlyDeletion,
+    onlyInsertion,
+    replacement,
+    summary,
+    diffs,
+  };
+}
+
+/** 片段截断展示，避免过长 */
+function formatSnippet(s: string, maxLen = 40): string {
+  const t = s.replace(/\s+/g, ' ').trim();
+  if (t.length <= maxLen) return t;
+  return `${t.slice(0, maxLen)}…`;
+}
+
+/**
+ * 根据当前内容和 range，找到下一个内容对应的 range
+ * 用于将 currentContent 中的 range 映射到 nextContent 中对应的 range
+ *
+ * @param options.currentContent 当前文件内容
+ * @param options.nextContent 下一个文件内容
+ * @param options.currentRange 当前文件中需要映射的 range
+ * @returns 映射得到的 nextRange、对应片段、以及片段级变更分析；若无法解析则返回 undefined
+ */
+export function resolveGroupChangeFragments(options: {
+  currentContent: string;
+  nextContent: string;
+  currentRange: Range;
+}):
+  | {
+      nextRange: Range;
+      currentFragment: string;
+      nextFragment: string;
+      changeAnalysis: FragmentChangeAnalysis;
+    }
+  | undefined {
+  const { currentContent, nextContent, currentRange } = options;
+
+  const { start: startOffset, end: endOffset } = currentRange;
+
+  if (
+    startOffset < 0 ||
+    endOffset < 0 ||
+    startOffset > endOffset ||
+    endOffset > currentContent.length
+  ) {
+    return undefined;
+  }
+
+  const nextRange = mapOlderRangeToNewer(
+    currentContent,
+    nextContent,
+    startOffset,
+    endOffset
+  );
+
+  const currentFragment = currentContent.substring(startOffset, endOffset);
+  const nextFragment = nextContent.substring(nextRange.start, nextRange.end);
+
+  const changeAnalysis = analyzeFragmentChange(currentFragment, nextFragment);
+
+  return {
+    nextRange,
+    currentFragment,
+    nextFragment,
+    changeAnalysis,
+  };
+}