ExportDXF/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• Root solution: ExportDXF.sln.
• WinForms app: ExportDXF/ExportDXF/ (.NET Framework 4.8; SolidWorks automation). Key folders: Forms/, Services/, Models/, Utilities/, Templates/, Resources/, ItemExtractors/, ViewFlipDeciders/, Extensions/, Properties/.
• Companion utilities: EtchBendLines/ (standalone solution for DXF processing; includes vendored netDxf).
• Sample docs: TestDocs/ contains drawings/fixtures useful for local validation.
• Tests: none yet; add new test projects under tests/ (e.g., tests/ExportDXF.Tests/).

Build, Test, and Development Commands

• Restore: msbuild ExportDXF.sln /t:Restore (or nuget restore ExportDXF.sln).
• Build (Release): msbuild ExportDXF.sln /p:Configuration=Release.
• Build single project: msbuild ExportDXF/ExportDXF/ExportDXF.csproj /p:Configuration=Release.
• Run app: ExportDXF/ExportDXF/bin/Release/ExportDXF.exe (or bin/Debug/ExportDXF.exe after a Debug build).
• Prereqs: Visual Studio 2019/2022 or Build Tools with .NET Framework 4.8 targeting pack; SolidWorks installed for automation features (app starts without SW but SW-dependent actions require it).
• Format: dotnet format from repo root if .NET SDK is installed; otherwise use VS “Format Document”.

Coding Style & Naming Conventions

• C#: 4-space indent, braces on new lines, nullable where supported.
• Naming: PascalCase for types/methods; camelCase for locals/fields; Async suffix for async methods.
• Structure: Keep UI in Forms/ thin; delegate work to Services/ and Utilities/. One class per file; filename matches type (e.g., DxfExportService.cs).
• Interop: Isolate SolidWorks COM/interop behind interfaces for testability; prefer dependency injection where practical.

Testing Guidelines

• Framework: xUnit recommended. Name files *Tests.cs and methods MethodName_Should_DoThing.
• Location: tests/ExportDXF.Tests/ with reference to the app or extracted class libraries.
• Scope: Favor service- and utility-level tests; avoid UI surface. Mock/abstract SolidWorks interop.
• Run: dotnet test (add when tests exist).

Commit & Pull Request Guidelines

• Messages: imperative, present tense with optional scope (e.g., ExportDXF: improve DXF export options). Provide rationale in body and any breaking changes.
• PRs include: clear description, linked issues (Closes #123), screenshots/GIFs for UI, migration notes, and local run steps.

Security & Configuration Tips

• Do not commit secrets or license keys.
• App configuration resides in app.config; user/machine-specific settings should stay in user config and not be committed.
• Keep SolidWorks version/paths configurable where possible.

Agent Tools: Roslyn Bridge (C# Analysis)

• Purpose: Use for C# code analysis, symbol queries, diagnostics, and semantic navigation via a local WebAPI bridge to Roslyn.

• Golden rules:

  • Always use this tool first for any C#/Roslyn analysis; do not guess.
  • Always check service health/instances before querying.
  • Default to solutionName=ExportDXF for this repo. If you intentionally open and analyze EtchBendLines.sln, use solutionName=EtchBendLines.

• Service assumptions:

  • WebAPI listens on http://localhost:5001 when installed and running.
  • Visual Studio must have the target solution open for the instance to appear.

• Quick workflow (ExportDXF):

  • List VS instances: curl http://localhost:5001/api/instances
  • Health check: curl http://localhost:5001/api/health
  • Diagnostics summary: curl "http://localhost:5001/api/roslyn/diagnostics/summary?solutionName=ExportDXF"
  • Errors only: curl "http://localhost:5001/api/roslyn/diagnostics?solutionName=ExportDXF&severity=error"
  • Warnings only: curl "http://localhost:5001/api/roslyn/diagnostics?solutionName=ExportDXF&severity=warning"
  • All diagnostics: curl "http://localhost:5001/api/roslyn/diagnostics?solutionName=ExportDXF"
  • List projects: curl "http://localhost:5001/api/roslyn/projects?solutionName=ExportDXF"
  • Solution overview: curl "http://localhost:5001/api/roslyn/solution/overview?solutionName=ExportDXF"
  • Find symbol by name: curl "http://localhost:5001/api/roslyn/symbol/search?solutionName=ExportDXF&symbolName=TypeOrMember"
  • Symbol at file/position: curl "http://localhost:5001/api/roslyn/symbol?solutionName=ExportDXF&filePath=C:/full/path/File.cs&line=10&column=5"
  • Find references: curl "http://localhost:5001/api/roslyn/references?solutionName=ExportDXF&filePath=C:/full/path/File.cs&line=10&column=5"

• Notes:

  • Lines are 1-based; columns are 0-based. Use absolute file paths.
  • Get canonical file paths from the projects endpoint responses.
  • Prefer this tool over manual grepping for symbols/references/diagnostics.

• Troubleshooting:

  • No instances listed: ensure Visual Studio is running with the solution open; wait up to 60s for discovery.
  • Service not reachable: verify the Roslyn Bridge WebAPI service is installed and running on port 5001.

• Helper script:

  • scripts/rb.ps1 provides short commands with defaults for this repo (defaults to -SolutionName ExportDXF).
  • Examples: ./scripts/rb.ps1 summary, ./scripts/rb.ps1 projects, ./scripts/rb.ps1 symbol -SymbolName Program.