Pabulib (.pb) - VS Code Extension

Language support for the .pb participatory budgeting file format used by Pabulib.

Features

Syntax Highlighting

Full syntax highlighting for .pb files including section headers, META keys/values, project data, and vote data.

Validation

Real-time diagnostics catch common errors:

• Missing required META fields (description, country, unit, instance, budget, vote_type, rule, etc.)
• Wrong types: num_projects/num_votes must be integers, budget/cost must be numbers, flag fields (fully_funded, experimental, min_project_score_threshold) must be integers
• Mismatch between num_projects/num_votes and actual counts
• Invalid vote_type or rule values
• Invalid date formats, invalid calendar dates (e.g. Feb 30), and date_begin after date_end
• Duplicate project IDs or voter IDs
• References to non-existent project IDs in votes
• Points exceeding max_sum_points for cumulative votes
• Vote length outside min_length/max_length bounds
• Invalid selected value (must be 0, 1, 2, or 3)
• Invalid fully_funded value (must be 1); warned when flag is missing but budget strictly exceeds total project cost, or set when it shouldn't be
• Invalid sex value in votes (must be M, F, or O)
• Invalid voting_method value in votes (must be internet or paper)
• Duplicate project IDs within a single vote
• Pre-computed votes/score columns in PROJECTS not matching actual counts from the VOTES section
• Projects with cost exceeding total budget

IntelliSense

Smart completions for:

• META field names with descriptions
• Valid values for vote_type (approval, ordinal, cumulative, scoring, choose-1)
• Valid values for rule (greedy, equalshares, etc.)
• Project IDs when entering votes
• Existing categories and targets from the file

Hover Information

Hover over elements to see details:

• META keys: Description and valid values from the spec
• Budget value: Percentage of total project costs covered by the budget
• Category cells in PROJECTS: Other projects sharing the hovered category (per individual category in a comma-separated list)
• Project IDs in votes: Project name, cost, categories, and vote count
• Voter IDs: Number of projects voted for and total points given

Code Navigation

• Go to Definition (Ctrl/Cmd+Click): Jump from a project ID in a vote to its definition in PROJECTS
• Find All References: See all votes that include a specific project
• Rename Symbol (F2): Rename a project ID across the entire file

Quick Fixes

Click the lightbulb or press Ctrl/Cmd+. for fixes:

• Update num_projects or num_votes to match actual counts
• Add missing required META fields
• Sort projects by votes, cost, or ID

Document Outline

View file structure in the Outline panel:

• META, PROJECTS, and VOTES sections
• Summary statistics (project count, vote count, budget)

Folding

Collapse each section independently for easier navigation.

The PB File Format

The .pb format stores participatory budgeting data in three sections:

META
key;value
description;Municipal PB in Example City
country;Country
unit;Example City
instance;2024
num_projects;3
num_votes;5
budget;100000
vote_type;approval
rule;greedy
date_begin;01.09.2024
date_end;30.09.2024

PROJECTS
project_id;cost;name;category
1;30000;New Park;environment
2;50000;Road Repair;infrastructure
3;25000;Library Books;education

VOTES
voter_id;vote
v1;1,2
v2;2,3
v3;1
v4;1,3
v5;2

For the full specification, see pabulib.org.

Installation

From Source

1. Clone this repository
2. Run npm install
3. Run npm run compile
4. Press F5 in VS Code to launch the Extension Development Host

Development

npm install       # Install dependencies
npm run compile   # Build the extension
npm run watch     # Watch for changes
npm run lint      # Run ESLint

License

MIT