Add empty folder export, folder comments, and / escaping

[AndrianBdn]

closes https://github.com/Hypersequent/tms-issues/issues/2215

Implements features from Hypersequent/tms-issues#2215 (partially covered by #5, which had review feedback that is addressed here):

• Empty folder export — AddFolder(folder, comment) API to create folders with no test cases. Folder-only rows are written when a folder is empty or has a comment.
• Folder comments — New "Folder Comment" CSV column. Comments are set via AddFolder and rendered on a dedicated folder row — this feature has been tested on staging of 26W06
• / in folder names — Removed excludesall=/ validation. / in folder segments is escaped as \/ in the joined path. Folder segments ending with \ are rejected to prevent ambiguity.
• jsonMarshal with SetEscapeHTML(false) — Prevents Go's default json.Marshal from mangling &, <, > into \u0026, \u003c, \u003e in JSON fields.
• Insertion-order folders — Folders appear in CSV in the order they were added, not alphabetically sorted.

PR #5 review feedback addressed

satvik007 comment	Status
Folder escaping is dead code due to excludesall=/ validation	Fixed — removed validation, escaping is now active
"You also need to trim stray \ at the end of folder name"	Added — segments ending with \ are rejected
CSV row uses strings.Join(tc.Folder, "/") instead of escaped map key	Fixed — uses escaped key from folderTCaseMap
jsonMarshal newline: "Is there some TrimSuffix function for this"	Fixed — uses bytes.TrimSuffix
Folder sorting is alphabetical vs DB position order	Fixed — preserves insertion order

Test plan

• All existing tests updated and passing
• New unit tests for: slash escaping, backslash rejection, empty folders, folder comments, folder with comment + test cases, AddFolder validation, slash in folder names
• Manual import verification using go run examples/functional/main.go (generates folder_comments.csv, empty_folders.csv, escaping.csv)

[gemini-code-assist]

Summary of Changes

Hello @AndrianBdn, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the qasphere-csv library by introducing robust folder management capabilities. It allows users to define empty folders and associate comments with them, improving the clarity and structure of exported test case data. Furthermore, it refines folder path handling by enabling and correctly escaping forward slashes, while also ensuring that JSON content within CSV fields is marshalled without unintended HTML escaping. These changes collectively provide greater flexibility and accuracy in generating QA Sphere-compatible CSV files.

Highlights

• Empty Folder Export: Introduced an AddFolder(folder, comment) API that allows creating folders without test cases. Folder-only rows are now written to the CSV when a folder is empty or has an associated comment.
• Folder Comments: Added a new 'Folder Comment' column to the CSV output. Comments can be set via the AddFolder API and are rendered on dedicated folder rows.
• Forward Slash Escaping in Folder Names: Removed the excludesall=/ validation, enabling forward slashes in folder segments. Slashes are now escaped as \/ in the joined folder path. Validation was added to reject folder segments ending with a backslash to prevent ambiguity.
• JSON Marshalling for CSV Fields: Implemented a custom jsonMarshal function that uses json.NewEncoder with SetEscapeHTML(false) to prevent Go's default JSON marshaller from escaping HTML characters like &, <, > into Unicode sequences within CSV fields.
• Insertion-Order Folders: Modified the CSV generation logic to preserve the insertion order of folders, rather than sorting them alphabetically.
• Addressed Previous Review Feedback: Incorporated feedback from a previous pull request (Add empty folder export, change Steps format #5), specifically regarding folder escaping, trimming stray backslashes, using escaped map keys for CSV rows, trimming newlines from jsonMarshal output, and maintaining folder insertion order.

Changelog

• .gitignore
  • Added *.csv to ignore generated CSV files.
• examples/functional/main.go
  • Added a new example file to demonstrate the new AddFolder functionality, including folder comments, empty folders, and slash escaping.
• qacsv_test.go
  • Updated successTestCasesCSV and customFieldSuccessTestCasesCSV to include the new 'Folder Comment' column.
  • Modified failureTestCases to reflect new validation rules for folder segments (empty segment, backslash ending).
  • Added new tests for folder slash escaping, folder segments ending with backslash, adding empty folders, adding folders with comments, adding folders with comments and test cases, and comprehensive AddFolder validation.
• qascsv.go
  • Imported the bytes package and removed the slices package import.
  • Added 'Folder Comment' to the staticColumns slice.
  • Removed the excludesall=/ validation tag from the TestCase.Folder struct field.
  • Added folderCommentMap (to store comments) and folderOrder (to maintain insertion order) fields to the QASphereCSV struct.
  • Modified NewQASphereCSV to initialize folderCommentMap.
  • Implemented a new AddFolder method to allow explicit creation of folders with optional comments and validation for folder paths and segments.
  • Added validateFolderSegments function to check for invalid folder segment characters (e.g., ending with backslash).
  • Added escapeFolderPath function to escape forward slashes in folder segments.
  • Modified validateTestCase to use validateFolderSegments for folder path validation.
  • Updated addTCase to use escapeFolderPath and to record new folders in folderOrder if they don't already exist.
  • Modified getFolders to return q.folderOrder instead of alphabetically sorting map keys, ensuring insertion order.
  • Implemented a custom jsonMarshal function that disables HTML escaping and trims trailing newlines.
  • Updated getCSVRows to handle folder comments, write folder-only rows for empty or commented folders, and use the new jsonMarshal for JSON fields.

Activity

• The pull request directly addresses and implements features requested in Hypersequent/tms-issues#2215.
• It incorporates and resolves specific review feedback from a previous pull request (Add empty folder export, change Steps format #5) by satvik007, including fixes for folder escaping, backslash trimming, correct CSV row generation, jsonMarshal newline handling, and folder sorting.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces valuable features like empty folder exports, folder comments, and support for slashes in folder names, with well-implemented changes and tests. However, a security audit revealed a high-severity Stored XSS vulnerability due to disabled HTML escaping during JSON marshalling, and a medium-severity CSV Injection vulnerability from unsanitized folder comments. Addressing these security concerns is critical. Additionally, there's a suggestion to improve code consistency.

[satvik007]

This should also be renamed to FolderPath, it will make the purpose of the field more clear.