evdboom_Bindery/CONTRIBUTING.md

Contributing to Bindery

Thank you for contributing! This document explains how to run the tests and what CI requires before a pull request can be merged.

---

Running Tests Locally

Quick test (all packages)

npm test  # runs all packages in parallel

Or test individual packages:

npm run test --workspace=bindery-core
npm run test --workspace=bindery-merge
npm run test --workspace=mcp-ts
npm run test --workspace=vscode-ext
npm run test --workspace=obsidian-plugin

Watch mode (auto-rerun on file change)

# Terminal 1
npm run test:watch --workspace=bindery-core

# Terminal 2
npm run test:watch --workspace=bindery-merge

# Terminal 3
npm run test:watch --workspace=mcp-ts

# Terminal 4
npm run test:watch --workspace=vscode-ext

# Terminal 5
npm run test:watch --workspace=obsidian-plugin

CI reporter (as GitHub Actions runs it)

cd mcp-ts && npm run test:ci
cd ../vscode-ext && npm run test:ci

The test:ci script writes a test-results.json file in each package directory that GitHub Actions uploads as a workflow artifact.

---

Test Coverage

Layer	Location	What is tested
bindery-core unit tests	bindery-core/test/	Templates, settings, translations, formatting logic
bindery-merge unit tests	bindery-merge/test/merge.test.ts	Pure merge functions, chapter discovery, dialect conversion
bindery-merge mocked tests	bindery-merge/test/merge-mocked.test.ts	Pandoc/LibreOffice paths (with child_process mocked)
bindery-merge extended tests	bindery-merge/test/merge-extended.test.ts	Internal functions, Pandoc helpers, typography integration
MCP unit tests	mcp-ts/test/tools.test.ts	Tool logic, path safety, search indexing
MCP contract tests	mcp-ts/test/index-contract.test.ts	Every registered tool has exactly one annotation hint
MCP stdio integration	mcp-ts/test/integration-stdio.test.ts	Spawn real server, JSON-RPC handshake, tool calls, path-traversal defence, error handling
VS Code unit tests	vscode-ext/test/workspace.test.ts, vscode-ext/test/mcp.test.ts	Workspace helpers, MCP JSON writer
VS Code integration	vscode-ext/test/integration-commands.test.ts	Init workflow, registerMcp, formatDocument, settings precedence
Obsidian plugin tests	obsidian-plugin/test/	Plugin lifecycle, workspace management, AI setup, merge execution, formatter integration
Obsidian exporter	obsidian-plugin/test/exporter.test.ts	Export orchestration, multi-format output
Obsidian merge	obsidian-plugin/test/merge.test.ts	Chapter discovery, dialect handling, Obsidian Vault API integration

---

Test Ownership Policy

To keep tests maintainable as packages grow, place tests where the production code lives:

1. Unit tests live in the owning package.
   • Example: template rendering logic in bindery-core/src/templates/** should be tested primarily in bindery-core/test/.
2. Cross-package tests validate wiring, contracts, and integration only.
   • Example: mcp-ts should keep a thin shim/contract test for re-exports, not duplicate full behavior suites owned by bindery-core.
3. Coverage exclusions should reflect testability, not ownership drift.
   • Do not exclude files from package coverage solely because tests were placed in a different package.

---

Host Feature Parity Policy

Feature parity is complete. Both vscode-ext/ and obsidian-plugin/ implement identical Bindery authoring workflows:

• Shared logic: All merge, export, tool-location, and typography logic lives in bindery-merge/ and is consumed by both hosts.
• Equivalent commands: Both hosts provide all 17+ authoring commands (format, merge, AI setup, workspace management, dialect/translation/language management).
• Equivalent tests: Each host has a full test suite covering its command wiring and host-specific integration (Obsidian Vault API, VS Code Workspace API).

Unless a feature is explicitly host-specific (e.g., VS Code's Language Model Tool API), any functional change or bug fix added to one host must be implemented in the other host in the same PR.

When adding or changing commands:

• Update logic: If logic lives in bindery-merge/ or bindery-core/, update there once
• Update command wiring: Update in both vscode-ext/src/extension.ts and obsidian-plugin/src/main.ts
• Add tests: Add to both host test suites to validate host-specific integration
• Document exceptions: Clearly note any intentional host-specific behavior in the PR description

---

MCP stdio integration tests (mcp-ts/test/integration-stdio.test.ts)

These tests spawn node out/index.js as a real child process and drive it over stdin/stdout using the MCP JSON-RPC protocol.

Prerequisites: run npm run build in mcp-ts/ before running these tests. The CI workflow does this automatically (build step runs before test:ci), but when running locally you must build first.

Security note: The tests use OS temporary directories created by mkdtempSync and never accept user-controlled paths, eliminating path-injection risk.

---

VS Code extension integration tests (vscode-ext/test/integration-commands.test.ts)

These tests exercise the full command-level workflows of the extension by calling the underlying helper functions directly (no extension-host required). The VS Code APIs are mocked via vi.mock('vscode', ...).

Tests cover:

• bindery.init — creates .bindery/settings.json and translations.json
• bindery.registerMcp — generates .vscode/mcp.json with the correct server config
• bindery.formatDocument — applies typography transforms (curly quotes, em-dash, ellipsis)
• Settings precedence (workspace file overrides defaults)

---

CI pipeline (.github/workflows/ci.yml)

The workflow runs on every push and pull request on all branches, on all three major platforms (Ubuntu, Windows, macOS).

A single test job runs the build and test steps sequentially:

Step	What it does
Install all workspace deps	npm ci
Build + test bindery-core	npm run build → npm run test:ci → uploads test-results.json
Build + test bindery-merge	npm run build → npm run test:ci → uploads test-results.json
Compile + test mcp-ts	npm run compile → npm run test:ci → uploads test-results.json
Compile + test vscode-ext	npm run compile → npm run test:ci (+ VSIX smoke check on ubuntu-latest)
Compile + test obsidian-plugin	npm run compile → npm run bundle → npm run test:ci → uploads test-results.json

A separate coverage job runs on ubuntu-latest only (coverage metrics don't vary by OS):

Step	What it does
Build + coverage for each package	npm run compile → npm run test:coverage
Upload coverage reports	Artifacts collected for each package

PRs cannot be merged unless the test job passes on all platforms.

---

Adding New Tests

1. Add your test file alongside the existing ones (mcp-ts/test/ or vscode-ext/test/).
2. Follow the naming convention: <feature>.test.ts for unit tests, integration-<area>.test.ts for integration tests.
3. Run npm test locally before pushing.
4. For MCP stdio integration tests that spawn a child process, always register a kill() call in afterEach to prevent orphaned processes.

---

Troubleshooting

Merge tests won't compile

The merge tests have moved from vscode-ext/test/ to bindery-merge/test/. If you have local references to the old paths, update imports to point to bindery-merge instead.

CI passes locally but fails in GitHub Actions

Ensure your package-lock.json was generated with the same npm major version as the one used in .github/workflows/ci.yml. This prevents lockfile skew across platforms.

---

Future Enhancements

• E2E tests with real pandoc/LibreOffice invocation
• Code coverage reporting dashboards
• Per-commit performance benchmarks (merge speed, search latency)