Check for vulnerable dependencies

May 5, 2026 · View on GitHub

Hack23 Logo

🤝 Contributing to EU Parliament Monitor

Code · Tests · Docs · Translations · Political Intelligence · Security
🇪🇺 Civic-tech for European democracy · 🛡️ Security-by-design · 🌍 14 languages · ♿ WCAG 2.1 AA

Owner Version Classification Review Cycle Effective

Code of Conduct Security Policy Hack23 ISMS OpenSSF Best Practices

📋 Document Owner: CEO | 📄 Version: 1.2 | 📅 Last Updated: 2026-04-27 (UTC) 🔄 Review Cycle: Quarterly | ⏰ Next Review: 2026-07-27 | 🏷️ Classification: Public

Thank you for your interest in contributing to EU Parliament Monitor — the open-source European Parliament political-intelligence platform that publishes AI-generated, evidence-based analysis in 14 languages every day. We welcome contributions from developers, journalists, translators, political scientists, OSINT analysts, accessibility advocates, and security researchers.

📑 Table of Contents

💜 Code of Conduct

This project adheres to the Contributor Covenant 2.1. By participating, you agree to maintain a respectful and inclusive environment. Report unacceptable behaviour to conduct@hack23.com.

👥 Who Should Contribute

🎭 Role🎯 What you can do
👨‍💻 DevelopersTypeScript aggregator, MCP integrations, GitHub Actions, accessibility, performance
📰 JournalistsEditorial style review, political analysis quality, source attribution discipline
🌐 TranslatorsImprove any of the 14 languages (EN, SV, DA, NO, FI, DE, FR, ES, NL, AR, HE, JA, KO, ZH)
🧠 Political scientists / OSINT analystsMethodologies under analysis/methodologies/, threat-framework refinement, ACH/SWOT/PESTLE rigor
♿ Accessibility advocatesWCAG 2.1 AA audits, RTL improvements (Arabic, Hebrew), screen-reader testing
🛡️ Security researchersResponsible disclosure via SECURITY.md — see also SECURITY_ARCHITECTURE.md and THREAT_MODEL.md
📚 Doc authorsArchitecture docs (ARCHITECTURE.md), C4 diagrams, ADRs, runbooks

🚀 Getting Started

📋 Prerequisites

  • 🟢 Node.js ≥ 26 (the platform runtime — see package.json engines.node)
  • 📦 npm ≥ 10 (ships with Node.js 26)
  • 🔧 Git

Setup

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/euparliamentmonitor.git
cd euparliamentmonitor
  3. Install dependencies: 
    npm install
  4. Create a branch for your changes: 
    git checkout -b feature/your-feature-name

🛠️ Development Workflow

▶️ Running Locally

# Render an article from analysis artifacts (manual testing)
npm run generate-article -- --run analysis/daily/2025-01-01/week-ahead

# Generate index pages
npm run generate-news-indexes

# Generate sitemap
npm run generate-sitemap

# Serve locally
npm run serve

Code Quality Checks

Before committing, run these checks:

# Lint your code
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format your code
npm run format

# Check formatting
npm run format:check

# Validate HTML
npm run htmlhint

✅ Code Quality Requirements

All contributions must meet these quality standards:

Testing Requirements

All contributions must include appropriate tests:

Unit & Integration Tests (Vitest)

  • Unit Tests: Write unit tests for new functions and modules
  • Integration Tests: Add integration tests for new workflows
  • Coverage: Maintain ≥80% line coverage, ≥75% branch coverage
  • Test Quality: Follow AAA pattern (Arrange, Act, Assert)
  • No Flaky Tests: Ensure tests are deterministic and reliable
# Run unit & integration tests
npm test

# Check coverage
npm run test:coverage

# Run specific test file
npx vitest test/unit/your-test.test.js

End-to-End Tests (Playwright)

  • E2E Tests: Add E2E tests for user-facing features
  • Accessibility: Ensure WCAG 2.1 AA compliance
  • Responsive Design: Test on mobile and desktop viewports
  • Cross-Browser: Tests run on Chromium, Firefox, and WebKit
# Run E2E tests
npm run test:e2e

# Run with UI (interactive debugging)
npm run test:e2e:ui

# Run in headed mode (see browser)
npm run test:e2e:headed

When to add E2E tests:

  • New user-facing features (navigation, forms, etc.)
  • Changes to page structure or layout
  • Multi-language functionality changes
  • Accessibility improvements
  • Responsive design changes

Required for all code changes:

  • New functions must have unit tests
  • New features must have integration tests
  • User-facing features should have E2E tests
  • All tests must pass before PR submission
  • Coverage thresholds must be met

ESLint

  • Zero errors required (warnings are acceptable for false positives)
  • All functions must have complete JSDoc documentation
  • Code complexity must be ≤15 (cognitive complexity)
  • No security vulnerabilities (eval, unsafe regex, etc.)

Prettier

  • All JavaScript files must be formatted with Prettier
  • Use the project's .prettierrc.json configuration
  • 100 character line width
  • Single quotes for strings

JSDoc Documentation

All exported functions must include:

/**
 * Brief function description
 * @param {type} paramName - Parameter description
 * @returns {type} Return value description
 */

Security

Security Architecture: All security changes must align with the Security Architecture and ISMS Secure Development Policy.

Security Requirements:

  • Never commit secrets or API keys
  • Use === instead of ==
  • Avoid eval() and new Function()
  • Validate all user inputs (see Security Controls)
  • Prevent XSS vulnerabilities (multi-layer defense: validation, sanitization, encoding, CSP)
  • No SQL injection risks (static site, no databases)
  • Test security-critical paths (≥95% coverage)
  • Follow threat model mitigations (see Threat Model)

Security Review Checklist:

  • Input validation implemented for all external data
  • HTML sanitization applied (script tags, event handlers removed)
  • Output encoding used (HTML entity encoding)
  • No new dependencies without security scanning (npm audit)
  • Security tests added for new attack surfaces
  • Documentation updated (SECURITY_ARCHITECTURE.md if applicable)
  • Threat model reviewed for new threats

Security Testing:

# Run security audit
npm audit

# Run security-focused tests
npm run test:unit -- --grep="security|xss|injection|sanitize"

# Check for vulnerable dependencies
npm audit --audit-level=moderate

Pre-commit Hooks

The project uses Husky and lint-staged to automatically:

  1. Run ESLint with auto-fix on staged JavaScript files
  2. Format staged files with Prettier
  3. Validate HTML files with htmlhint
  4. Run affected tests (if configured)

These hooks run automatically on git commit. To bypass (not recommended):

git commit --no-verify

📝 Commit Guidelines

Commit Message Format

Use conventional commits format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests (use this for test-related commits!)
  • chore: Maintenance tasks
  • ci: CI/CD changes

Examples

git commit -m "feat(news): add breaking news article type"
git commit -m "fix(mcp): handle connection timeout gracefully"
git commit -m "docs: update code standards documentation"
git commit -m "refactor(generator): reduce complexity in generateWeekAhead"
git commit -m "test: add unit tests for article template"
git commit -m "test: increase coverage for MCP client"

🔀 Pull Request Process

Before Submitting

  1. Run all quality checks:

    npm run lint
npm run format:check
npm run htmlhint
npm test
npm run test:e2e

  2. Check test coverage:

    npm run test:coverage
# Ensure coverage thresholds are met
# Lines: ≥80%, Branches: ≥75%

  3. Test your changes:

    # Render an article from analysis (if applicable)
npm run generate-article -- --run analysis/daily/YYYY-MM-DD/week-ahead

# Verify output
npm run generate-news-indexes
npm run generate-sitemap

# Test E2E (if UI changes)
npm run test:e2e:headed

  4. Update documentation if you've:

    • Added new features
    • Changed APIs or interfaces
    • Modified configuration
    • Added new test files (update test/README.md or e2e/README.md)

PR Checklist

  • Code follows the project's code standards
  • All ESLint checks pass (0 errors)
  • Code is formatted with Prettier
  • All functions have JSDoc documentation
  • All unit & integration tests pass (npm test)
  • E2E tests pass (npm run test:e2e) (if UI changes)
  • Test coverage meets thresholds (≥80% lines, ≥75% branches)
  • New code has corresponding tests
  • No security vulnerabilities introduced
  • Documentation updated (if needed)
  • Commit messages follow conventional commits format

PR Description

Include in your PR description:

  1. What: Brief description of the change
  2. Why: Reason for the change
  3. How: Technical approach used
  4. Testing: How you tested the changes
  5. Screenshots: For UI changes

CI/CD Checks

Your PR must pass these automated checks:

  • ✅ ESLint (zero errors)
  • ✅ Prettier formatting
  • ✅ HTML validation
  • ✅ JavaScript syntax check
  • ✅ Unit tests
  • ✅ Integration tests
  • ✅ E2E tests (runs daily and on PRs)
  • ✅ Coverage thresholds (80%/75%)
  • ✅ Security audit (npm audit)
  • ✅ Functional tests

Review Process

  1. Automated checks must pass
  2. At least one maintainer review required
  3. All review comments must be addressed
  4. PR will be merged by a maintainer

📂 Project Structure

euparliamentmonitor/
├── .github/              # GitHub workflows and configuration
│   ├── workflows/        # CI/CD workflows + agentic workflows (news-*.md)
│   └── agents/          # Custom GitHub Copilot agents
├── scripts/             # Compiled JavaScript from src/
│   ├── aggregator/      # Article generation aggregator
│   ├── generators/      # Index & sitemap generators
│   └── mcp/             # MCP clients
├── src/                 # TypeScript source
│   ├── aggregator/      # Analysis aggregation + article rendering
│   ├── generators/      # Sitemap, indexes, political intelligence
│   ├── mcp/             # MCP client implementations
│   ├── utils/           # Utilities (file, metadata, sanitize)
│   ├── types/           # TypeScript type definitions
│   └── constants/       # Configuration constants
├── test/                # Unit & integration tests
│   ├── unit/            # Unit tests
│   ├── integration/     # Integration tests
│   ├── fixtures/        # Test data
│   └── helpers/         # Test utilities
├── e2e/                 # End-to-end tests
│   ├── tests/           # E2E test files
│   └── README.md        # E2E testing guide
├── news/                # Generated news articles
├── docs/                # Documentation
│   └── CODE_STANDARDS.md # Code quality standards
├── .husky/              # Pre-commit hooks
├── eslint.config.js     # ESLint configuration
├── .prettierrc.json     # Prettier configuration
├── playwright.config.js # Playwright E2E configuration
└── package.json         # Dependencies and scripts

🤖 Custom Agents

EU Parliament Monitor ships with a layered agent catalog under .github/agents/ — product-domain agents that own the news critical path, plus infrastructure agents that maintain workflow and CI hygiene. See .github/agents/README.md for the full directory and the .github/skills/ and .github/prompts/ libraries that they share.

🎭 Product-domain agents (own the news critical path)

AgentRole
🕵️ @intelligence-operativeSenior political-intelligence analyst — applies ACH, SWOT, PESTLE, OSINT tradecraft, threat framework. Owns Stage-B analysis artifacts.
📰 @news-journalistThe Economist-style EP reporting in 14 languages. Authors editorial prose only when analysis artifacts are signed off.
🔄 @data-pipeline-specialistEP MCP integration (60+ tools), data quality, voting-records fallback to EP Open Data Portal.
🎨 @frontend-specialistHTML5/CSS3, WCAG 2.1 AA accessibility, multi-language UI, RTL support.
✅ @quality-engineerVitest + Playwright, HTML validation, accessibility testing, performance benchmarking.
⚙️ @devops-engineergh-aw workflow compilation, GitHub Actions, S3/CloudFront deploy, MCP gateway.
📚 @documentation-architectC4 models, Mermaid diagrams, ARCHITECTURE.md, ADRs.
🛡️ @security-architectISMS, GDPR, NIS2, EU CRA compliance — reviews data classification of intelligence products.
📋 @product-task-agentIssue creation, ISMS tracking, capability-roadmap coordination.
📣 @marketing-specialistPrivacy-first multi-language engagement, GDPR-compliant outreach.
💼 @business-development-specialistStrategic planning, civic-tech partnerships, sustainable transparency models.

🛠️ Infrastructure agents (maintain workflows and CI hygiene)

agentic-workflows.agent.md · news-generation.agent.md · ci-cleaner.agent.md · contribution-checker.agent.md · create-safe-output-type.agent.md · custom-engine-implementation.agent.md · grumpy-reviewer.agent.md · interactive-agent-designer.agent.md · technical-doc-writer.agent.md · w3c-specification-writer.agent.md

🐛 Debugging

# View TypeScript compilation
npm run build:check

# Test article generation (requires existing analysis artifacts)
npm run generate-article -- --run analysis/daily/YYYY-MM-DD/article-type

🧩 Adding a new analysis template

Analysis templates live under analysis/templates/. Every template is the AI's contract for one artifact under analysis/daily/<date>/<run>/…. To add a new template:

  1. Pick the artifact name — it must match the analysis/daily/<run>/… filename you want the AI to produce (e.g. risk-cascade.md).
  2. Add the methodology section — open analysis/methodologies/per-artifact-methodologies.md and add a ### risk-cascade section describing construction rules, required H2s, and quality signals.
  3. Add the catalog row — append a row to analysis/methodologies/artifact-catalog.md under the right group (intelligence / classification / risk-scoring / threat-assessment / extended) so the script can resolve methodology + Mermaid type.
  4. Add the depth floor — add a key under each relevant articleType in analysis/methodologies/reference-quality-thresholds.json (the breaking floor is the one printed in the front-matter).
  5. Drop the template — create analysis/templates/risk-cascade.md with the SPDX header pair, your title, and at least one section. The body can be minimal at first.
  6. Run the sync — npm run sync:templates. The script injects the canonical ANALYSIS-TEMPLATE-FRONTMATTER:v1 and AI-INSTRUCTIONS:v1 blocks. Re-run with --check for CI.
  7. Reference the template — link to it from at least one prompt under .github/prompts/ or one agent under .github/agents/ (otherwise test/unit/analysis-templates-referenced.test.js fails).
  8. Run the drift-guard — npx vitest run test/unit/template-structure.test.js.

Shared chunks live in analysis/templates/_partials/ — link to them from your template instead of duplicating the citation pattern, evidence table, IMF callout, or quality checklist.

💻 IDE Setup

VS Code Extensions:

  • ESLint
  • Prettier
  • HTMLHint

VS Code Settings:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

❓ Questions?

  • Open an issue for bugs or feature requests
  • Check docs/CODE_STANDARDS.md for code guidelines
  • Review existing code for examples
  • Contact maintainers via GitHub

🏆 Security Badge Maintenance

Contributing to Badge Status

When contributing, be aware of how your changes may affect security badges:

OpenSSF Scorecard

Your PR may affect the scorecard if it:

  • Modifies GitHub Actions workflows
  • Adds/removes dependencies
  • Changes branch protection settings
  • Adds security scanning tools

Best Practices:

  • Pin all GitHub Actions to SHA hashes (not tags)
  • Use maintained, official actions when possible
  • Add security tests for new attack surfaces
  • Keep dependencies up-to-date

REUSE Compliance

All new files must include proper license headers or be covered by .reuse/dep5:

For JavaScript files:

// SPDX-FileCopyrightText: 2024-2026 Hack23 AB
// SPDX-License-Identifier: Apache-2.0

For configuration files: Add entries to .reuse/dep5 following existing patterns

Test Coverage

New code must maintain ≥80% line coverage, ≥75% branch coverage:

  • Add unit tests for new functions
  • Add integration tests for new workflows
  • Add E2E tests for user-facing features

SonarCloud Quality Gate

When SonarCloud is enabled, PRs will be checked for:

  • Code coverage (target: 80%)
  • Code smells and technical debt
  • Security vulnerabilities
  • Maintainability rating (target: A)

See README.md - Badge Maintenance for detailed badge status and procedures.

🛡️ ISMS Compliance & Security-Policy Alignment

EU Parliament Monitor operates under the Hack23 ISMS framework. All contributions must align with these public policies — both in code (Secure Development Policy) and in conduct (Acceptable Use Policy).

🏛️ Policy🎯 Why it applies📌 What you must do
🛠️ Secure Development PolicyAll code changes go through SSDLC gatesThreat-model new pipelines; pin actions to SHAs; no eval/dynamic code
📋 Information Security PolicyIntegrity of analysis + confidentiality of methodology notesCite primary EP / IMF / World Bank sources; never leak credentials
🤖 AI PolicyAnalysis is AI-assisted and must be auditableApply Pass-1 + Pass-2 review; disclose assumptions and uncertainty
🏷️ Classification PolicyOnly public open-source material is usedNo paywalled, leaked, or embargoed material in artifacts
🐛 Vulnerability ManagementSeverity-based remediation SLAsFollow the SECURITY.md disclosure timeline
🔍 Threat Modelling PolicyNew attack surfaces require STRIDE analysisUpdate THREAT_MODEL.md for changes that touch CIA assets
🔐 Cryptography PolicyNo deprecated algorithms (MD5, SHA-1, DES, 3DES)Use modern crypto only; rely on platform / OIDC primitives
🚒 Incident Response PlanCoordinated handling of security incidentsNotify security@hack23.com for any suspected incident
📜 Open Source PolicyGovernance, licence headers, REUSE complianceApache-2.0 SPDX headers on every new code file
🇪🇺 CRA Conformity AssessmentEU Cyber Resilience Act complianceSee CRA-ASSESSMENT.md for the project conformity table

📚 Internal docs every contributor should know

TopicDocument
🏛️ ArchitectureARCHITECTURE.md · DATA_MODEL.md · FLOWCHART.md · STATEDIAGRAM.md · MINDMAP.md
📰 Article generationArticle-Generation.md — full Stage A→E pipeline
🧠 Analysis methodologyanalysis/methodologies/ (17 methodologies) · analysis/templates/ (51 templates)
🛡️ SecuritySECURITY.md · SECURITY_ARCHITECTURE.md · THREAT_MODEL.md · CRA-ASSESSMENT.md · CLASSIFICATION.md
⚙️ CI/CDWORKFLOWS.md · .github/workflows/README.md · .github/prompts/README.md
🧪 TestingUnitTestPlan.md · E2ETestPlan.md · test/README.md · e2e/README.md
💼 Business / lifecycleSWOT.md · BCPPlan.md · End-of-Life-Strategy.md · FinancialSecurityPlan.md

🌐 Hack23 Ecosystem

EU Parliament Monitor is part of the broader Hack23 civic-tech and security portfolio. Cross-pollination is welcome — many architectural patterns and ISMS controls are shared.

🏛️ Project🎯 Focus🔗 Link
🌐 Hack23 HomepageOrganisation site, ISMS hubhack23.com · Hack23/homepage
📜 ISMS-PUBLICPublic ISO 27001 / NIST CSF / CIS / GDPR / NIS2 / EU CRA policiesHack23/ISMS-PUBLIC
🔌 European Parliament MCP ServerTypeScript MCP server with 60+ EP open-data toolsHack23/European-Parliament-MCP-Server
🇸🇪 Riksdag MonitorSwedish Parliament monitor (sister project, foundation for this codebase)Hack23/riksdagsmonitor
🕵️ CIASwedish Parliament intelligence platform (Java/Spring)Hack23/cia
✅ CIA Compliance ManagerCIA-triad compliance dashboard (TypeScript)Hack23/cia-compliance-manager
🥋 Black TrigramKorean martial-arts game with security focusHack23/blacktrigram

📜 License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0 — the same licence that covers the rest of the project. All new code files must include SPDX headers:

// SPDX-FileCopyrightText: 2024-2026 Hack23 AB
// SPDX-License-Identifier: Apache-2.0

Configuration files without headers must be covered by entries in .reuse/dep5.

🙏 Thank you for contributing to EU Parliament Monitor! 🇪🇺

Maintained by Hack23 AB — Intelligence Operations Team under the Hack23 ISMS framework.