# DESA — Contributors Guide

> **Version:** 1.0.0
> **Maintained by:** [Platphorm News](https://platphormnews.com)
> **Last Updated:** 2025-03-07

## Welcome

Thank you for your interest in contributing to **DESA (Dynamic Encoded Script Analysis)**. This guide covers how to contribute effectively to the project and the broader [PlatphormNews network](https://platphormnews.com).

## Code of Conduct

All contributors are expected to adhere to respectful, inclusive, and constructive communication. We follow the [Contributor Covenant](https://www.contributor-covenant.org/) v2.1.

## How to Contribute

### Reporting Issues

- Search existing [issues](https://github.com/mbarbine/desa-powershell-script-analysis/issues) before opening a new one.
- Provide clear reproduction steps, expected vs. actual behavior, and environment details.
- Label issues appropriately: `bug`, `enhancement`, `documentation`, `security`.

### Submitting Changes

1. **Fork** the repository and create a feature branch from `main`.
2. **Install dependencies:** `npm install`
3. **Run tests:** `npx vitest run`
4. **Lint:** `npm run lint`
5. **Build:** `npm run build`
6. **Commit** with clear, descriptive messages following [Conventional Commits](https://www.conventionalcommits.org/).
7. **Open a Pull Request** targeting the `main` branch.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/mbarbine/desa-powershell-script-analysis.git
cd desa-powershell-script-analysis

# Install dependencies
npm install

# Copy environment template
cp .env.example .env.local

# Start development server
npm run dev

# Run tests
npx vitest run
```

### Project Structure

| Directory | Purpose |
|-----------|---------|
| `app/` | Next.js 16 app router (pages, API routes, metadata) |
| `components/` | React components (UI, SEO, layout, viewers) |
| `lib/` | Core libraries (analysis engine, MCP, integrations, API) |
| `docs/` | Project documentation (architecture, roadmap, API spec) |
| `public/` | Static assets (icons, LLM context files) |
| `scripts/` | Build and utility scripts |
| `styles/` | Global stylesheets |

### Coding Standards

- **Language:** TypeScript (strict mode)
- **Framework:** Next.js 16 with React 19
- **Styling:** Tailwind CSS v4 with Radix UI primitives
- **Testing:** Vitest with React Testing Library
- **Linting:** ESLint
- **Formatting:** Consistent with existing codebase conventions

### Detection Rule Contributions

DESA has 20+ built-in detection rules. To contribute a new rule:

1. Add the rule definition to the analysis engine
2. Include MITRE ATT&CK mapping where applicable
3. Add test cases covering true positives and false positives
4. Document the rule's detection logic and severity

### Documentation

- Keep docs in sync with code changes
- Follow the markdown style of existing docs
- API changes should update `docs/API.md` and the OpenAPI spec

## Contributors

### Core Team

- **Platphorm News** — Project maintainer and network operator
  - Website: [platphormnews.com](https://platphormnews.com)
  - Twitter: [@platphormnews](https://twitter.com/platphormnews)

### AI Agents

This project uses AI-assisted development. Agent journals are maintained in `.jules/`:
- `bolt.md` — Performance optimization insights
- `sentinel.md` — Security vulnerability learnings
- `palette.md` — UX/accessibility insights

## License

This project is licensed under the MIT License. See [LICENSE](../LICENSE) for details.

## Links

- **Repository:** [github.com/mbarbine/desa-powershell-script-analysis](https://github.com/mbarbine/desa-powershell-script-analysis)
- **Documentation:** [desa.platphormnews.com/docs](https://desa.platphormnews.com/docs)
- **PlatphormNews:** [platphormnews.com](https://platphormnews.com)
- **MCP Hub:** [mcp.platphormnews.com](https://mcp.platphormnews.com)