scancscode 1.0.37 → 1.0.38

package/.trae/specs/add-codesnippet-field-comments/checklist.md

@@ -0,0 +1,11 @@
+*- [x] originalIndex 字段有定义注释
+- [x] originalContext 字段有定义注释
+- [x] originalCode 字段有定义注释
+- [x] convertedCode 字段有定义注释
+- [x] literals 字段有定义注释
+- [x] unexpects 字段有定义注释
+- [x] isChanged 访问器属性有定义注释
+- [x] 所有 124 个测试用例都通过
+- [x] 注释使用 JSDoc 格式
+- [x] 注释准确描述每个字段的用途
+

package/.trae/specs/add-codesnippet-field-comments/spec.md

@@ -0,0 +1,59 @@
+# 给 CodeSnippet 类的公开字段添加定义注释 - Product Requirement Document
+
+## Overview
+- **Summary**: 给 CodeSnippet 类的所有公开字段添加清晰的定义注释
+- **Purpose**: 提高代码的可读性和可维护性，让开发者更容易理解每个字段的用途
+- **Target Users**: 使用 CSharpStringExtractor 和 CodeSnippet 类的开发者
+
+## Goals
+- 给 CodeSnippet 类的所有公开字段添加 JSDoc 格式的定义注释
+- 确保注释清晰、准确地描述每个字段的用途
+- 保持代码风格一致
+
+## Non-Goals (Out of Scope)
+- 不修改字段的功能或实现
+- 不修改私有字段
+- 不添加新的功能
+
+## Background & Context
+CodeSnippet 类是 CSharpStringExtractor 的核心数据结构，用于存储提取的字符串片段信息。目前该类的公开字段缺少详细的定义注释，影响了代码的可读性。
+
+## Functional Requirements
+- **FR-1**: 给 CodeSnippet 类的所有公开字段添加定义注释
+- **FR-2**: 注释使用 JSDoc 格式，便于 IDE 提示和文档生成
+
+## Non-Functional Requirements
+- **NFR-1**: 所有现有测试用例必须通过
+- **NFR-2**: 代码风格保持一致
+
+## Constraints
+- **Technical**: 使用 TypeScript 语言，遵循 JSDoc 注释风格
+- **Business**: 不影响现有功能
+
+## Assumptions
+- 公开字段包括：originalIndex, originalContext, originalCode, convertedCode, literals, unexpects
+- 公开字段还包括：isChanged 访问器属性
+- addLiteral 和 finalizeLiterals 方法已经有适当的实现
+
+## Acceptance Criteria
+
+### AC-1: 所有公开字段都有定义注释
+- **Given**: CodeSnippet 类的代码
+- **When**: 检查每个公开字段
+- **Then**: 每个公开字段都有清晰的 JSDoc 格式注释
+- **Verification**: `human-judgment`
+
+### AC-2: 所有现有测试通过
+- **Given**: 修改后的代码
+- **When**: 运行完整测试套件
+- **Then**: 所有测试用例都应该通过
+- **Verification**: `programmatic`
+
+### AC-3: 注释准确描述字段用途
+- **Given**: 字段的注释
+- **When**: 与实际代码使用情况对比
+- **Then**: 注释准确反映字段的实际用途
+- **Verification**: `human-judgment`
+
+## Open Questions
+- 无

package/.trae/specs/add-codesnippet-field-comments/tasks.md

@@ -0,0 +1,14 @@
+# 给 CodeSnippet 类的公开字段添加定义注释 - The Implementation Plan (Decomposed and Prioritized Task List)
+
+## [x] Task 1: 给 CodeSnippet 类的公开字段添加定义注释
+- **Priority**: P0
+- **Depends On**: None
+- **Description**: 
+  - 给 CodeSnippet 类的所有公开字段添加 JSDoc 格式的定义注释
+  - 字段包括：originalIndex, originalContext, originalCode, convertedCode, literals, unexpects
+  - 还包括：isChanged 访问器属性
+- **Acceptance Criteria Addressed**: [AC-1, AC-2, AC-3]
+- **Test Requirements**:
+  - `programmatic` TR-1.1: 所有 124 个测试用例都通过
+  - `human-judgement` TR-1.2: 所有公开字段都有清晰、准确的 JSDoc 注释
+- **Notes**: 在 2-22 行进行修改，根据测试用例和实际使用情况确定每个字段的准确含义

package/.trae/specs/fix-return-original-index/checklist.md

@@ -0,0 +1,4 @@
+- [x] "should handle return string" 测试用例通过
+- [x] 所有 124 个测试用例都通过
+- [x] originalIndex 的值等于 fullCode.indexOf(originalCode)
+- [x] 代码修改遵循 TypeScript 语法和现有风格

package/.trae/specs/fix-return-original-index/spec.md

@@ -0,0 +1,74 @@
+# 修复 return 语句的 originalIndex 计算 - Product Requirement Document
+
+## Overview
+
+### **Summary**: 修复 CSharpStringExtractor 中处理 return 语句时 originalIndex 的计算错误问题
+
+### **Purpose**: 确保提取的字符串片段的 originalIndex 正确对应代码中实际位置
+
+### **Target Users**: 使用 CSharpStringExtractor 的开发者
+
+### Goals
+
+### 修复 "should handle return string" 测试用例失败的问题
+
+### 确保 originalIndex = code.indexOf(originalCode) 的正确性
+
+### Non-Goals (Out of Scope)
+
+* 不修改其他功能的实现逻辑
+
+* 不添加新的测试用例
+
+## Background & Context
+
+当前测试用例 "should handle return string" 失败，原因是 originalIndex 的值不正确（期望 130，实际 199）。问题出在 extractValueExpression 方法中处理 return 语句时，没有像处理赋值语句那样在 fullCode 中查找实际的 valueExpression 位置。
+
+## Functional Requirements
+
+* **FR-1**: 对于 return 语句，正确计算 valueExpression 的 originalIndex
+
+* **FR-2**: originalIndex 应该等于 fullCode.indexOf(originalCode)
+
+## Non-Functional Requirements
+
+* **NFR-1**: 所有现有测试用例必须通过
+
+## Constraints
+
+* **Technical**: 使用 TypeScript 语言，遵循现有代码风格
+
+* **Business**: 不影响现有功能
+
+## Assumptions
+
+* 测试用例的预期结果是正确的
+
+* 其他语句类型（如赋值语句）的 originalIndex 计算是正确的
+
+## Acceptance Criteria
+
+### AC-1: return 语句的 originalIndex 正确
+
+* **Given**: 包含 return 语句的 C# 代码
+
+* **When**: extractStrings 方法被调用
+
+* **Then**: 返回的 snippet 的 originalIndex 应该等于 code.indexOf(originalCode)
+
+* **Verification**: `programmatic`
+
+### AC-2: 所有现有测试通过
+
+* **Given**: 修改后的代码
+
+* **When**: 运行完整测试套件
+
+* **Then**: 所有测试用例都应该通过
+
+* **Verification**: `programmatic`
+
+## Open Questions
+
+* 无
+

package/.trae/specs/fix-return-original-index/tasks.md

@@ -0,0 +1,14 @@
+# 修复 return 语句的 originalIndex 计算 - The Implementation Plan (Decomposed and Prioritized Task List)
+
+## [x] Task 1: 修复 extractValueExpression 方法中 return 语句的 originalIndex 计算
+- **Priority**: P0
+- **Depends On**: None
+- **Description**: 
+  - 修改 extractValueExpression 方法中处理 return 语句的代码
+  - 在计算 finalIndex 时，添加在 fullCode 中查找 valueExpression 实际位置的逻辑
+  - 参考赋值语句的处理方式
+- **Acceptance Criteria Addressed**: [AC-1, AC-2]
+- **Test Requirements**:
+  - `programmatic` TR-1.1: "should handle return string" 测试用例通过
+  - `programmatic` TR-1.2: 所有 123 个测试用例都通过
+- **Notes**: 在 2396-2431 行进行修改，参考赋值语句的处理（2434-2451 行）

package/dist/src/CSharpStringExtractor.js

@@ -2,11 +2,29 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CSharpStringExtractor = exports.CodeSnippet = void 0;
 class CodeSnippet {
+    /**
+     * 代码片段在原始源代码中的起始位置索引
+     */
     originalIndex;
+    /**
+     * 原始上下文，与 originalCode 相同，保存原始的代码片段内容
+     */
     originalContext;
+    /**
+     * 从源代码中提取的原始代码片段
+     */
     originalCode;
+    /**
+     * 经过国际化处理后的代码片段，可能添加了 .TR() 调用或转换为 Tr.Format(...) 形式
+     */
     convertedCode;
+    /**
+     * 从代码片段中提取出的字符串字面量数组，已进行去重和标准化处理
+     */
     literals;
+    /**
+     * 意外情况记录数组
+     */
     unexpects;
     literalPositions;
     constructor() {
@@ -18,6 +36,10 @@ class CodeSnippet {
         this.unexpects = [];
         this.literalPositions = new Map();
     }
+    /**
+     * 判断代码片段是否经过修改
+     * @returns 如果 convertedCode 与 originalCode 不同则返回 true，否则返回 false
+     */
     get isChanged() {
         return this.originalCode !== this.convertedCode;
     }
@@ -2156,29 +2178,10 @@ class CSharpStringExtractor {
             const valuePart = trimmedStatement.substring('return '.length);
             const value = this.extractValueUntilSemicolon(valuePart);
             const valueExpression = value.trim();
-            let finalIndex = statementIndex;
-            const returnKeywordInStatement = statement.indexOf('return ');
-            if (returnKeywordInStatement !== -1) {
-                const afterReturnInStatement = returnKeywordInStatement + 'return '.length;
-                let startInStatement = -1;
-                for (let i = afterReturnInStatement; i < statement.length - 1; i++) {
-                    if (statement[i] === '$' && statement[i + 1] === '"') {
-                        startInStatement = i;
-                        break;
-                    }
-                }
-                if (startInStatement === -1) {
-                    for (let i = afterReturnInStatement; i < statement.length; i++) {
-                        if (statement[i] === '"') {
-                            startInStatement = i;
-                            break;
-                        }
-                    }
-                }
-                if (startInStatement !== -1) {
-                    finalIndex = statementIndex + startInStatement;
-                }
-            }
+            const valueStartInStatement = statement.indexOf(value);
+            const valueExpressionIndex = statementIndex + (valueStartInStatement !== -1 ? valueStartInStatement : 'return '.length);
+            const actualValueStart = fullCode.indexOf(valueExpression, valueExpressionIndex);
+            const finalIndex = actualValueStart !== -1 ? actualValueStart : valueExpressionIndex;
             return {
                 valueExpression: valueExpression,
                 valueExpressionIndex: finalIndex

package/dist/src/CmdExecutor.js

@@ -13,9 +13,8 @@ function isNullOrEmpty(arr) {
 class CmdExecutor {
     static testConvert() {
         let cwd = "E:/DATA/Projects/ZhiYou/ProjectFClient/GameClient/";
-        let cscodeFolders = 
-        // [cwd + "Assets/Bundles/FGUI/"]
-        [
+        let cscodeFolders = [
+            cwd + "Assets/Bundles/FGUI/",
             "E:/DATA/Projects/ZhiYou/DXTSProject/Client/Assets/Bundles/UI/",
             "E:/DATA/Projects/ZhiYou/DXTSProject/Client/Assets/Bundles/Battle/",
             "E:/DATA/Projects/ZhiYou/DXTSProject/Client/Assets/Scripts/",

package/dist/test/CSharpStringExtractor.test.js

@@ -2252,7 +2252,7 @@ namespace FaBao.UI.MainUI
         }
     });
     // 测试处理 `xxx.text = yyy` 形式赋值语句, 以 `.text =` 给 `text` 成员赋值的表达式中, `yyy` 部分必定是字符串表达式; 如果`yyy`中不存在字符串, 则`yyy` 中以 `+` 连接的表达式需要加上 `.TR()`; 如果 `yyy` 是作为值表达式整体(必定返回字符串类型值), 也需要追加 `.TR()`。
-    test('should handle .text = format 1', () => {
+    test('should handle .text = format 2', () => {
         const code = `m_text_info.text = info1.member1 + info2.member2;`;
         const snippets = extractor.extractStrings(code);
         {
@@ -2438,4 +2438,36 @@ namespace FaBao.UI.MainUI
         const snippets = extractor.extractStrings(code);
         expect(snippets.length).toBe(0);
     });
+    // 需要正确获取 `originalIndex`, `originalIndex` 的定义为 `originalIndex=code.indexOf(originalCode)`, 其中 `code` 表示原始代码, `originalCode` 表示匹配出的原始代码中的字符串表达式
+    test('should handle calculate originalIndex', () => {
+        const code = `
+namespace FaBao
+{
+    public partial class UserInfoModel
+    {
+        public bool HasJoinedGuild()
+        {
+            return !string.IsNullOrEmpty(MyGuildInfo.GuildId) && MyGuildInfo.GuildId != "0";
+        }
+
+        public void UpdateBargain(BargainShopData bargainShopData)
+        {
+            MyGuildInfo.IsBargainShopBargain = true;
+        }
+
+    }
+}
+`;
+        const snippets = extractor.extractStrings(code);
+        {
+            let targetSnippet = snippets[0];
+            expect(targetSnippet.originalCode).toBe(`!string.IsNullOrEmpty(MyGuildInfo.GuildId) && MyGuildInfo.GuildId != "0"`);
+            expect(targetSnippet.originalIndex).toBe(code.indexOf(`!string.IsNullOrEmpty(MyGuildInfo.GuildId) && MyGuildInfo.GuildId != "0"`));
+            expect(targetSnippet.convertedCode).toBe(`!string.IsNullOrEmpty(MyGuildInfo.GuildId) && MyGuildInfo.GuildId != "0"`);
+            expect(targetSnippet.literals).toEqual([
+                '0'
+            ]);
+            expect(targetSnippet.isChanged).toBe(false);
+        }
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scancscode",
-  "version": "1.0.37",
+  "version": "1.0.38",
   "description": "",
   "main": "./dist/index.js",
   "bin": {

package/src/CSharpStringExtractor.ts

@@ -1,9 +1,27 @@
 export class CodeSnippet {
+    /**
+     * 代码片段在原始源代码中的起始位置索引
+     */
     originalIndex: number;
+    /**
+     * 原始上下文，与 originalCode 相同，保存原始的代码片段内容
+     */
     originalContext: string;
+    /**
+     * 从源代码中提取的原始代码片段
+     */
     originalCode: string;
+    /**
+     * 经过国际化处理后的代码片段，可能添加了 .TR() 调用或转换为 Tr.Format(...) 形式
+     */
     convertedCode: string;
+    /**
+     * 从代码片段中提取出的字符串字面量数组，已进行去重和标准化处理
+     */
     literals: string[];
+    /**
+     * 意外情况记录数组
+     */
     unexpects: string[];
     private literalPositions: Map<number, string>;
 
@@ -17,6 +35,10 @@ export class CodeSnippet {
         this.literalPositions = new Map();
     }
 
+    /**
+     * 判断代码片段是否经过修改
+     * @returns 如果 convertedCode 与 originalCode 不同则返回 true，否则返回 false
+     */
     get isChanged(): boolean {
         return this.originalCode !== this.convertedCode;
     }
@@ -2398,32 +2420,11 @@ private findMatchingParenthesis(str: string, openIndex: number): number {
             const value = this.extractValueUntilSemicolon(valuePart);
             const valueExpression = value.trim();
 
-            let finalIndex = statementIndex;
-            const returnKeywordInStatement = statement.indexOf('return ');
-            if (returnKeywordInStatement !== -1) {
-                const afterReturnInStatement = returnKeywordInStatement + 'return '.length;
-                let startInStatement = -1;
-                
-                for (let i = afterReturnInStatement; i < statement.length - 1; i++) {
-                    if (statement[i] === '$' && statement[i + 1] === '"') {
-                        startInStatement = i;
-                        break;
-                    }
-                }
-                
-                if (startInStatement === -1) {
-                    for (let i = afterReturnInStatement; i < statement.length; i++) {
-                        if (statement[i] === '"') {
-                            startInStatement = i;
-                            break;
-                        }
-                    }
-                }
-                
-                if (startInStatement !== -1) {
-                    finalIndex = statementIndex + startInStatement;
-                }
-            }
+            const valueStartInStatement = statement.indexOf(value);
+            const valueExpressionIndex = statementIndex + (valueStartInStatement !== -1 ? valueStartInStatement : 'return '.length);
+
+            const actualValueStart = fullCode.indexOf(valueExpression, valueExpressionIndex);
+            const finalIndex = actualValueStart !== -1 ? actualValueStart : valueExpressionIndex;
 
             return {
                 valueExpression: valueExpression,

package/src/CmdExecutor.ts

@@ -10,13 +10,12 @@ export class CmdExecutor {
     static testConvert() {
         let cwd = "E:/DATA/Projects/ZhiYou/ProjectFClient/GameClient/"
         let cscodeFolders =
-            // [cwd + "Assets/Bundles/FGUI/"]
-
-        [
-        "E:/DATA/Projects/ZhiYou/DXTSProject/Client/Assets/Bundles/UI/",
-         "E:/DATA/Projects/ZhiYou/DXTSProject/Client/Assets/Bundles/Battle/",
-         "E:/DATA/Projects/ZhiYou/DXTSProject/Client/Assets/Scripts/",
-        ]
+            [
+                cwd + "Assets/Bundles/FGUI/",
+                "E:/DATA/Projects/ZhiYou/DXTSProject/Client/Assets/Bundles/UI/",
+                "E:/DATA/Projects/ZhiYou/DXTSProject/Client/Assets/Bundles/Battle/",
+                "E:/DATA/Projects/ZhiYou/DXTSProject/Client/Assets/Scripts/",
+            ]
 
         let gameConfigFolders = [cwd + "Assets/Bundles/GameConfigs/"]
         let outCsvFile = "E:/DATA/Projects/e-gbl-client/client/Assets/Bundles/GameConfigs/Translation/hello.csv"

package/test/CSharpStringExtractor.test.ts

@@ -2477,7 +2477,7 @@ namespace FaBao.UI.MainUI
     });
 
     // 测试处理 `xxx.text = yyy` 形式赋值语句, 以 `.text =` 给 `text` 成员赋值的表达式中, `yyy` 部分必定是字符串表达式; 如果`yyy`中不存在字符串, 则`yyy` 中以 `+` 连接的表达式需要加上 `.TR()`; 如果 `yyy` 是作为值表达式整体(必定返回字符串类型值), 也需要追加 `.TR()`。
-    test('should handle .text = format 1', () => {
+    test('should handle .text = format 2', () => {
         const code = `m_text_info.text = info1.member1 + info2.member2;`;
         const snippets = extractor.extractStrings(code);
         {
@@ -2676,4 +2676,37 @@ namespace FaBao.UI.MainUI
         expect(snippets.length).toBe(0);
     });
 
+    // 需要正确获取 `originalIndex`, `originalIndex` 的定义为 `originalIndex=code.indexOf(originalCode)`, 其中 `code` 表示原始代码, `originalCode` 表示匹配出的原始代码中的字符串表达式
+    test('should handle calculate originalIndex', () => {
+        const code = `
+namespace FaBao
+{
+    public partial class UserInfoModel
+    {
+        public bool HasJoinedGuild()
+        {
+            return !string.IsNullOrEmpty(MyGuildInfo.GuildId) && MyGuildInfo.GuildId != "0";
+        }
+
+        public void UpdateBargain(BargainShopData bargainShopData)
+        {
+            MyGuildInfo.IsBargainShopBargain = true;
+        }
+
+    }
+}
+`;
+        const snippets = extractor.extractStrings(code);
+        {
+            let targetSnippet = snippets[0];
+            expect(targetSnippet.originalCode).toBe(`!string.IsNullOrEmpty(MyGuildInfo.GuildId) && MyGuildInfo.GuildId != "0"`);
+            expect(targetSnippet.originalIndex).toBe(code.indexOf(`!string.IsNullOrEmpty(MyGuildInfo.GuildId) && MyGuildInfo.GuildId != "0"`));
+            expect(targetSnippet.convertedCode).toBe(`!string.IsNullOrEmpty(MyGuildInfo.GuildId) && MyGuildInfo.GuildId != "0"`);
+            expect(targetSnippet.literals).toEqual([
+                '0'
+            ]);
+            expect(targetSnippet.isChanged).toBe(false);
+        }
+    });
+
 });