Skip to content

Commit 8262bbb

Browse files
trendvidiatrendvidia
committed
Initial public release
Canonical, language-neutral specification for the protowire stack: - PXF (Proto eXpressive Format): EBNF grammar, railroad diagram, and reference fixtures for the human-friendly text format. - PB: protobuf binary with the (pxf.required) and (pxf.default) annotations under proto/pxf/. - SBE: FIX Simple Binary Encoding annotations under proto/sbe/. - Envelope: response envelope schema under proto/envelope/v1/. - Adversarial corpus + HARDENING.md invariants every port must honour, driven by scripts/cross_security_check.sh and tracked in testdata/adversarial/MANIFEST.jsonl. - Editor extensions for VS Code (.vsix) and JetBrains IDEs (.zip), shipping syntax highlighting + inline parse-error squiggles backed by the protowire-typescript and protowire-java parsers. - Cross-port byte-equivalence and benchmark harnesses under scripts/. See README.md for the full overview, STABILITY.md for the SemVer policy, SECURITY.md for the disclosure process, and ROADMAP.md for milestones.
0 parents  commit 8262bbb

102 files changed

Lines changed: 17567 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.editorconfig‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# EditorConfig — https://editorconfig.org
2+
# Applies to every editor that ships an EditorConfig plugin (most do).
3+
4+
root = true
5+
6+
[*]
7+
charset = utf-8
8+
end_of_line = lf
9+
insert_final_newline = true
10+
trim_trailing_whitespace = true
11+
indent_style = space
12+
indent_size = 2
13+
14+
[*.go]
15+
indent_style = tab
16+
indent_size = 4
17+
18+
[Makefile]
19+
indent_style = tab
20+
21+
[*.{md,markdown}]
22+
trim_trailing_whitespace = false # markdown uses trailing spaces for line breaks
23+
24+
[*.{kt,kts,java,gradle}]
25+
indent_size = 4
26+
27+
[*.py]
28+
indent_size = 4
29+
30+
[*.{rs,c,cc,cpp,h,hpp}]
31+
indent_size = 4

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
name: Bug report
3+
about: Report a defect — wrong output, crash, parse error on valid input, etc.
4+
title: "bug: "
5+
labels: bug
6+
---
7+
8+
<!--
9+
Cross-port issues (the same input produces different output on different
10+
ports, or one port crashes where others succeed) belong here, not in
11+
the per-port repo. See STABILITY.md and HARDENING.md.
12+
13+
Security issues — decoder crashes/hangs/OOMs on adversarial input —
14+
go to security@trendvidia.com instead. See SECURITY.md.
15+
-->
16+
17+
## What happened
18+
19+
A clear description of the bug.
20+
21+
## How to reproduce
22+
23+
Smallest possible PXF / PB / SBE / envelope input that triggers it.
24+
Inline if short, or attach as a file.
25+
26+
```pxf
27+
@type your.package.Type
28+
field = "value"
29+
```
30+
31+
## What you expected
32+
33+
What you thought should happen.
34+
35+
## Affected ports
36+
37+
- [ ] Go (`protowire-go`)
38+
- [ ] C++ (`protowire-cpp`)
39+
- [ ] Rust (`protowire-rust`)
40+
- [ ] Java (`protowire-java`)
41+
- [ ] TypeScript (`protowire-typescript`)
42+
- [ ] Python (`protowire-python`)
43+
- [ ] C# (`protowire-csharp`)
44+
- [ ] Swift (`protowire-swift`)
45+
- [ ] Dart (`protowire-dart`)
46+
- [ ] Spec / grammar / documentation only (no port code involved)
47+
48+
## Versions
49+
50+
- Affected port version(s):
51+
- `protowire` spec commit (if known):
52+
- OS / arch (only if it might matter):

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# SPDX-License-Identifier: MIT
2+
# Copyright (c) 2026 TrendVidia, LLC.
3+
4+
blank_issues_enabled: false
5+
contact_links:
6+
- name: Security vulnerability
7+
url: https://github.com/trendvidia/protowire/blob/main/SECURITY.md
8+
about: >-
9+
Decoder crashes, hangs, OOMs, or other vulnerabilities — email
10+
security@trendvidia.com per SECURITY.md, do not file a public
11+
issue.
12+
- name: Question or design discussion
13+
url: https://github.com/trendvidia/protowire/discussions
14+
about: >-
15+
For design questions, "is this the right approach", or anything
16+
that isn't a bug or a concrete feature ask, please use Discussions.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: Feature request
3+
about: Propose a new annotation, grammar addition, envelope field, or tooling improvement
4+
title: "feat: "
5+
labels: enhancement
6+
---
7+
8+
<!--
9+
Spec-level changes affect every port and need careful design. Proposals
10+
that touch the wire contract (annotation field numbers, envelope fields,
11+
PXF grammar) should outline the migration path for existing data.
12+
-->
13+
14+
## Problem
15+
16+
What can't you express today, or what's awkward to express?
17+
18+
## Proposal
19+
20+
What you'd like to add or change. If it's a wire-format change, include:
21+
22+
- A draft of the grammar / proto / SBE additions.
23+
- Whether existing valid input remains valid (additive vs. breaking).
24+
- How the change is detected and serialised on the wire.
25+
26+
## Alternatives considered
27+
28+
What else you tried, and why it isn't enough.
29+
30+
## Cross-port impact
31+
32+
Which of the nine ports would need to change, and roughly how much
33+
work each one looks like.
34+
35+
## Out of scope (optional)
36+
37+
Things this proposal is **not** trying to do, to keep review focused.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
<!--
2+
Spec-level PRs (grammar, proto, envelope, hardening corpus) usually
3+
require coordinated changes in every port. Mention which ports you've
4+
also opened PRs against, or flag the ones that are still pending.
5+
6+
For first-time contributors: see CONTRIBUTING.md for the workflow and
7+
the Steward governance rollout note.
8+
-->
9+
10+
## Summary
11+
12+
What this PR changes, in 1–3 sentences.
13+
14+
## Why
15+
16+
Link to the issue or discussion that motivated this. If there isn't
17+
one, briefly state the user-visible problem this solves.
18+
19+
## Scope
20+
21+
- [ ] Spec / grammar (`docs/grammar.ebnf`, `proto/`, `governance.pxf`)
22+
- [ ] Tooling (`scripts/`, `cmd/`, `editors/`)
23+
- [ ] Hardening corpus (`testdata/adversarial/`)
24+
- [ ] Documentation only
25+
26+
## Cross-port coordination
27+
28+
If this is a wire-format or grammar change, list every port it affects
29+
and the status of the matching PR there:
30+
31+
- [ ] protowire-go — link / status
32+
- [ ] protowire-cpp — link / status
33+
- [ ] protowire-rust — link / status
34+
- [ ] protowire-java — link / status
35+
- [ ] protowire-typescript — link / status
36+
- [ ] protowire-python — link / status
37+
- [ ] protowire-csharp — link / status
38+
- [ ] protowire-swift — link / status
39+
- [ ] protowire-dart — link / status
40+
41+
## Test plan
42+
43+
- [ ] `go vet ./... && go build ./... && go test -race ./...` passes
44+
- [ ] If this changes wire behaviour: relevant cross-port script has
45+
been re-run locally and produces identical output across all
46+
checked-out ports.
47+
- [ ] If this touches the adversarial corpus: every port's
48+
`check-decode` produces the verdict declared in `MANIFEST.jsonl`.
49+
- [ ] If this touches the editor extensions: the prebuilt `.vsix` /
50+
`.zip` in `dist/` has been refreshed.

‎.github/workflows/ci.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# SPDX-License-Identifier: MIT
2+
# Copyright (c) 2026 TrendVidia, LLC.
3+
4+
name: CI
5+
6+
# Base build/test workflow for the canonical CLI and codegen plugins.
7+
# Cross-port wire-equivalence and HARDENING conformance jobs are tracked
8+
# separately in ROADMAP.md (M1, M8) and will be re-introduced once the
9+
# Steward governance integration is finalised.
10+
11+
on:
12+
pull_request:
13+
push:
14+
branches: [main]
15+
16+
permissions:
17+
contents: read
18+
19+
jobs:
20+
test:
21+
runs-on: ubuntu-latest
22+
steps:
23+
- uses: actions/checkout@v6
24+
25+
- uses: actions/setup-go@v6
26+
with:
27+
go-version-file: go.mod
28+
cache: true
29+
30+
- name: go vet
31+
run: go vet ./...
32+
33+
- name: go build
34+
run: go build ./...
35+
36+
- name: go test
37+
run: go test -race ./...

‎.github/workflows/codeql.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# SPDX-License-Identifier: MIT
2+
# Copyright (c) 2026 TrendVidia, LLC.
3+
4+
name: CodeQL
5+
6+
# Static-analysis SAST for Go (the canonical CLI) and Kotlin (the
7+
# JetBrains plugin's startup activity / annotator). The protowire-java
8+
# parser jar bundled by the JetBrains plugin is owned by protowire-java;
9+
# CodeQL there is run in that repo, not here.
10+
11+
on:
12+
push:
13+
branches: [main]
14+
pull_request:
15+
branches: [main]
16+
schedule:
17+
# Weekly re-scan to catch newly-disclosed CodeQL queries firing on
18+
# unchanged code.
19+
- cron: "37 6 * * 1"
20+
21+
permissions:
22+
contents: read
23+
security-events: write
24+
25+
jobs:
26+
analyze:
27+
name: Analyze (${{ matrix.language }})
28+
runs-on: ubuntu-latest
29+
strategy:
30+
fail-fast: false
31+
matrix:
32+
language: [go, java-kotlin]
33+
steps:
34+
- uses: actions/checkout@v6
35+
36+
- if: matrix.language == 'go'
37+
uses: actions/setup-go@v6
38+
with:
39+
go-version-file: go.mod
40+
cache: true
41+
42+
- if: matrix.language == 'java-kotlin'
43+
uses: actions/setup-java@v5
44+
with:
45+
distribution: temurin
46+
java-version: 21
47+
48+
- uses: github/codeql-action/init@v3
49+
with:
50+
languages: ${{ matrix.language }}
51+
queries: security-and-quality
52+
53+
- if: matrix.language == 'go'
54+
run: go build ./...
55+
56+
- if: matrix.language == 'java-kotlin'
57+
working-directory: editors/jetbrains/plugin
58+
run: ./gradlew --quiet classes
59+
60+
- uses: github/codeql-action/analyze@v3
61+
with:
62+
category: "/language:${{ matrix.language }}"

‎.gitignore‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Editor / IDE
2+
.idea/
3+
.vscode/
4+
*.swp
5+
6+
# OS
7+
.DS_Store
8+
9+
# Built Go binaries (produced by `go build ./cmd/...`)
10+
/protowire
11+
/protoc-gen-pxf-java-meta
12+
13+
# VS Code extension build artifacts.
14+
# We commit editors/vscode/dist/pxf-*.vsix as the pre-built install asset.
15+
# The bundled extension.js is a build product and stays out of git.
16+
editors/vscode/node_modules/
17+
editors/vscode/dist/extension.js
18+
editors/vscode/dist/extension.js.map
19+
*.vsix
20+
!editors/vscode/dist/*.vsix
21+
22+
# JetBrains plugin build artifacts (from `./gradlew buildPlugin`).
23+
# We commit editors/jetbrains/plugin/dist/pxf-jetbrains-*.zip as a pre-built
24+
# install asset, so only ignore everything *except* dist/.
25+
editors/jetbrains/plugin/.gradle/
26+
editors/jetbrains/plugin/.intellijPlatform/
27+
editors/jetbrains/plugin/.kotlin/
28+
editors/jetbrains/plugin/build/
29+
editors/jetbrains/plugin/dist/*.zip
30+
!editors/jetbrains/plugin/dist/pxf-jetbrains-*.zip

‎CHANGELOG.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Changelog
2+
3+
This is the **spec-level** changelog: grammar bumps, envelope versions,
4+
annotation additions, and other things every port has to mirror. Per-port
5+
release notes live in each port's own changelog.
6+
7+
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
8+
loosely; the project follows [SemVer](https://semver.org/) per
9+
[`STABILITY.md`](STABILITY.md).
10+
11+
## [Unreleased]
12+
13+
### Changed
14+
15+
- **PXF grammar (breaking)** — `docs/grammar.ebnf` now distinguishes
16+
`field_entry` (identifier key + `=` or `{ … }`) from `map_entry`
17+
(id/string/integer key + `:`). At the document top level only
18+
`field_entry` is accepted; `map_entry` is reserved for the inside of
19+
`{ … }` blocks where it represents map literal entries. Inputs like
20+
`123 = 234` and top-level `123: 234` are now parse errors.
21+
- All ports' parsers must mirror this; new adversarial fixtures
22+
`testdata/adversarial/pxf/{integer-key-assignment,integer-key-in-block,top-level-map-entry}.pxf`
23+
fail any port that hasn't caught up.
24+
25+
### Added
26+
27+
- **Editor extensions** under [`editors/`](editors/) — VS Code (`.vsix`)
28+
and JetBrains (`.zip`) plugins shipping prebuilt for offline install.
29+
Both bundle their port's own parser (`protowire-typescript` and
30+
`protowire-java` respectively) for inline parse-error squiggles, plus
31+
a TextMate grammar for syntax highlighting.
32+
- **`docs/HARDENING.md`** adversarial corpus + per-port `check-decode`
33+
conformance harness, gated by
34+
[`scripts/cross_security_check.sh`](scripts/cross_security_check.sh).
35+
- **Project security policy** at [`SECURITY.md`](SECURITY.md) with a
36+
contact and a 30-day coordinated-disclosure embargo for cross-port
37+
issues.

‎CODE_OF_CONDUCT.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Code of Conduct
2+
3+
This project adopts the [Contributor Covenant, v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)
4+
as its code of conduct. Participants in the project — issue authors,
5+
pull request reviewers, maintainers, and anyone interacting in
6+
project spaces — are expected to follow it.
7+
8+
## Reporting
9+
10+
To report a concern, email **conduct@trendvidia.com**. Reports are read
11+
by the project maintainers only and are handled in confidence. We aim
12+
to acknowledge reports within three business days.
13+
14+
For security-sensitive reports (vulnerabilities, exploits), use the
15+
process in [`SECURITY.md`](SECURITY.md) instead.

0 commit comments

Comments
 (0)