diff --git a/doc/src/content/docs/guides/troubleshooting.mdx b/doc/src/content/docs/guides/troubleshooting.mdx index 5a5e54d..0314e4c 100644 --- a/doc/src/content/docs/guides/troubleshooting.mdx +++ b/doc/src/content/docs/guides/troubleshooting.mdx @@ -193,24 +193,26 @@ languages.go = { Cannot find module '@myorg/proto' ``` -**Solutions:** +**Solution:** -1. **Check package.json generation:** +Bufrnix no longer generates package.json files. You need to manage imports manually in your project. Either: - ```nix - languages.js = { - enable = true; - es = { - enable = true; - generatePackageJson = true; - packageName = "@myorg/proto"; - }; - }; +1. **Use relative imports:** + + ```typescript + import { User } from "./gen/js/user_pb.js"; ``` -2. **Install generated packages:** - ```bash - npm install ./gen/js # If package.json was generated +2. **Configure TypeScript path aliases in tsconfig.json:** + + ```json + { + "compilerOptions": { + "paths": { + "@myorg/proto/*": ["./gen/js/*"] + } + } + } ``` **Error: TypeScript type errors** diff --git a/doc/src/content/docs/reference/configuration.mdx b/doc/src/content/docs/reference/configuration.mdx index 89a9d5b..fd940ed 100644 --- a/doc/src/content/docs/reference/configuration.mdx +++ b/doc/src/content/docs/reference/configuration.mdx @@ -3,7 +3,17 @@ title: Configuration Reference description: Complete reference for all Bufrnix configuration options and settings with examples. --- -import { Card, CardGrid, Tabs, TabItem, Code, Badge, LinkCard, FileTree, Aside } from "@astrojs/starlight/components"; +import { + Card, + CardGrid, + Tabs, + TabItem, + Code, + Badge, + LinkCard, + FileTree, + Aside, +} from "@astrojs/starlight/components"; # Configuration Reference @@ -15,10 +25,12 @@ Bufrnix configuration prioritizes **explicitness over magic** and **reproducibil - All options are validated at evaluation time, catching errors before generation runs + All options are validated at evaluation time, catching errors before + generation runs - Same configuration = identical outputs across all environments and team members + Same configuration = identical outputs across all environments and team + members No hidden network calls or surprise downloads - everything declared upfront @@ -29,7 +41,9 @@ Bufrnix configuration prioritizes **explicitness over magic** and **reproducibil ## Basic Configuration Structure @@ -86,29 +100,21 @@ This approach trades some initial setup time for long-term reliability, making B python = { enable = true; outputPath = "gen/python"; }; # ... other languages }; - }; + +}; }`} - lang="nix" - title="Complete configuration structure" +lang="nix" +title="Complete configuration structure" /> -- project/ - - flake.nix ← Bufrnix configuration here - - proto/ - - user/v1/ - - user.proto - - gen/ ← Generated code output - - go/ - - python/ - - js/ + - project/ - flake.nix ← Bufrnix configuration here - proto/ - user/v1/ - + user.proto - gen/ ← Generated code output - go/ - python/ - js/ - }; -} -``` +}; } ``` ## Root Configuration @@ -218,7 +224,7 @@ languages = { ]; grpc.enable = true; }; - + js = { # Frontend: Public APIs + Google annotations additionalFiles = [ @@ -236,29 +242,29 @@ languages = { **Configuration Options:** -| Option | Type | Default | Description | -|--------|------|---------|-------------| -| `languages.*.files` | list of strings or null | `null` | Proto files for this language only. Overrides global `protoc.files` | -| `languages.*.additionalFiles` | list of strings | `[]` | Additional files to add to global `protoc.files` for this language | +| Option | Type | Default | Description | +| ----------------------------- | ----------------------- | ------- | ------------------------------------------------------------------- | +| `languages.*.files` | list of strings or null | `null` | Proto files for this language only. Overrides global `protoc.files` | +| `languages.*.additionalFiles` | list of strings | `[]` | Additional files to add to global `protoc.files` for this language | **Use Cases:** - **Problem**: Different services for different tiers - **Solution**: `go.files` for internal services, `js.additionalFiles` for public APIs + **Problem**: Different services for different tiers **Solution**: `go.files` + for internal services, `js.additionalFiles` for public APIs - **Problem**: Go + Google annotations = linting errors - **Solution**: Exclude Google annotations from Go, include in JavaScript + **Problem**: Go + Google annotations = linting errors **Solution**: Exclude + Google annotations from Go, include in JavaScript - **Problem**: Frontend accessing internal services - **Solution**: Use `files` to enforce strict separation at build time + **Problem**: Frontend accessing internal services **Solution**: Use `files` + to enforce strict separation at build time - **Problem**: All languages process all files - **Solution**: Each language processes only relevant files + **Problem**: All languages process all files **Solution**: Each language + processes only relevant files @@ -266,10 +272,11 @@ languages = { **Backward Compatible**: Existing configurations work unchanged. Per-language files are opt-in enhancements. **Migration Path**: + 1. Start with global `protoc.files` (current behavior) -2. Add `additionalFiles` for language-specific extensions +2. Add `additionalFiles` for language-specific extensions 3. Use `files` for complete per-language control - + ## Language Support @@ -364,22 +371,19 @@ Modern JavaScript/TypeScript support with multiple output formats and RPC framew languages.js = { enable = true; outputPath = "src/proto"; - packageName = "@myorg/proto"; # Modern ECMAScript modules with TypeScript (recommended) es = { enable = true; target = "ts"; # Generate TypeScript options = ["import_extension=.js"]; # ES module extensions - generatePackageJson = true; - packageName = "@myorg/proto-es"; + # Note: Manage your package.json file manually in your project }; # Connect-ES for modern RPC connect = { enable = true; - generatePackageJson = true; - packageName = "@myorg/proto-connect"; + # Note: Manage your package.json file manually in your project }; # gRPC-Web for browser compatibility @@ -404,20 +408,25 @@ languages.js = { tsProto = { enable = true; options = ["esModuleInterop=true" "useOptionals=messages"]; - generatePackageJson = true; generateTsConfig = true; + # Note: Manage your package.json file manually in your project }; }; ``` #### JavaScript Configuration Options -| Option | Type | Default | Description | -| ------------- | --------------- | ---------- | -------------------------------------------- | -| `enable` | boolean | `false` | Enable JavaScript/TypeScript code generation | -| `outputPath` | string | `"gen/js"` | Output directory for generated code | -| `packageName` | string | `""` | JavaScript package name | -| `options` | list of strings | `[]` | Options to pass to protoc JS plugins | +| Option | Type | Default | Description | +| ------------ | --------------- | ---------- | -------------------------------------------- | +| `enable` | boolean | `false` | Enable JavaScript/TypeScript code generation | +| `outputPath` | string | `"gen/js"` | Output directory for generated code | +| `options` | list of strings | `[]` | Options to pass to protoc JS plugins | + + ### Dart Configuration @@ -796,12 +805,10 @@ Here's a comprehensive example showing multiple languages configured together: js = { enable = true; outputPath = "web/src/proto"; - packageName = "@myorg/proto"; es = { enable = true; target = "ts"; - generatePackageJson = true; }; connect.enable = true; diff --git a/doc/src/content/docs/reference/languages.mdx b/doc/src/content/docs/reference/languages.mdx index 6ac35b1..229c383 100644 --- a/doc/src/content/docs/reference/languages.mdx +++ b/doc/src/content/docs/reference/languages.mdx @@ -595,16 +595,12 @@ languages = { es = { enable = true; # Enabled by default target = "ts"; # Options: "js", "ts", "dts" - generatePackageJson = true; - packageName = "@myproject/proto"; importExtension = ".js"; # For Node.js ES modules }; # Connect-ES - Modern RPC framework connect = { enable = true; # Integrated with protoc-gen-es v2 - generatePackageJson = true; - packageName = "@myproject/connect"; }; # Runtime validation support @@ -616,7 +612,6 @@ languages = { # Alternative: ts-proto for different style tsProto = { enable = false; # Set to true for interface-style TypeScript - generatePackageJson = true; generateTsConfig = true; options = [ "esModuleInterop=true" @@ -631,6 +626,9 @@ languages = { }; }; }; + +# Note: Bufrnix no longer generates package.json files. You should manage your +# package.json manually in your project. ``` ### Generated Code Features diff --git a/doc/src/content/docs/reference/languages/javascript.mdx b/doc/src/content/docs/reference/languages/javascript.mdx index fbf6893..e5ac0ba 100644 --- a/doc/src/content/docs/reference/languages/javascript.mdx +++ b/doc/src/content/docs/reference/languages/javascript.mdx @@ -3,7 +3,13 @@ title: JavaScript/TypeScript Language Support description: Modern Protocol Buffer support for JavaScript and TypeScript with ES modules, Connect-ES, gRPC-Web, and Twirp. --- -import { Tabs, TabItem, Badge, CardGrid, Card } from "@astrojs/starlight/components"; +import { + Tabs, + TabItem, + Badge, + CardGrid, + Card, +} from "@astrojs/starlight/components"; import { Code } from "astro:components"; import basicConfig from "./javascript.x-basic-configuration.nix?raw"; @@ -16,12 +22,12 @@ JavaScript/TypeScript support provides multiple output formats and RPC options f ## Available Plugins -| Plugin | Description | Generated Files | -| --------------------------- | ----------------- | ---------------------- | -| **`protoc-gen-js`** | CommonJS messages | `*_pb.js`, `*_pb.d.ts` | -| **`protoc-gen-es`** | ES modules | `*.js`, `*.d.ts` | -| **`protoc-gen-grpc-web`** | gRPC-Web client | `*_grpc_web_pb.js` | -| **`protoc-gen-twirp_js`** | Twirp RPC | `*_twirp.js` | +| Plugin | Description | Generated Files | +| ------------------------- | ----------------- | ---------------------- | +| **`protoc-gen-js`** | CommonJS messages | `*_pb.js`, `*_pb.d.ts` | +| **`protoc-gen-es`** | ES modules | `*.js`, `*.d.ts` | +| **`protoc-gen-grpc-web`** | gRPC-Web client | `*_grpc_web_pb.js` | +| **`protoc-gen-twirp_js`** | Twirp RPC | `*_twirp.js` | ## Configuration @@ -40,7 +46,6 @@ languages.js = { languages.js = { enable = true; outputPath = "src/proto"; - packageName = "@myorg/proto"; options = [ "import_style=commonjs" "binary" @@ -72,6 +77,9 @@ languages.js = { options = ["lang=typescript"]; }; }; + +# Note: Bufrnix no longer generates package.json files. You should manage your +# package.json manually in your project. ``` ## Per-Language Files @@ -164,10 +172,10 @@ languages.js = { ### Configuration Options -| Option | Type | Description | Example | -|--------|------|-------------|---------| -| `files` | `list` | Override global files completely | Web client APIs only | -| `additionalFiles` | `list` | Extend global files | Add Google annotations | +| Option | Type | Description | Example | +| ----------------- | ------ | -------------------------------- | ---------------------- | +| `files` | `list` | Override global files completely | Web client APIs only | +| `additionalFiles` | `list` | Extend global files | Add Google annotations | ### Common JavaScript Use Cases @@ -512,9 +520,7 @@ message StreamUsersRequest { // vite.config.ts export default { optimizeDeps: { - include: [ - "@bufbuild/protobuf", - ], + include: ["@bufbuild/protobuf"], }, }; ``` diff --git a/examples/js-es-modules/README.md b/examples/js-es-modules/README.md index 7ea43ca..a534b5a 100644 --- a/examples/js-es-modules/README.md +++ b/examples/js-es-modules/README.md @@ -117,13 +117,8 @@ languages = { es = { enable = true; # Enabled by default target = "ts"; # Generate TypeScript - generatePackageJson = true; # Create package.json importExtension = ".js"; # For Node.js compatibility }; - connect = { - enable = true; # Enable Connect-ES - generatePackageJson = true; - }; protovalidate = { enable = true; # Enable validation }; @@ -134,6 +129,8 @@ languages = { }; ``` +**Note**: You must manage your own `package.json` file with the appropriate dependencies for your project. See the example `package.json` in this directory. + ## Alternative: ts-proto You can also enable ts-proto for a different style of TypeScript generation: @@ -141,8 +138,6 @@ You can also enable ts-proto for a different style of TypeScript generation: ```nix tsProto = { enable = true; - generatePackageJson = true; - generateTsConfig = true; options = [ "esModuleInterop=true" "outputServices=nice-grpc" diff --git a/examples/js-es-modules/flake.lock b/examples/js-es-modules/flake.lock index 060b442..2c20c04 100644 --- a/examples/js-es-modules/flake.lock +++ b/examples/js-es-modules/flake.lock @@ -67,15 +67,15 @@ }, "nixpkgs_3": { "locked": { - "lastModified": 1748190013, - "narHash": "sha256-R5HJFflOfsP5FBtk+zE8FpL8uqE7n62jqOsADvVshhE=", - "owner": "NixOS", + "lastModified": 1766309749, + "narHash": "sha256-3xY8CZ4rSnQ0NqGhMKAy5vgC+2IVK0NoVEzDoOh4DA4=", + "owner": "nixos", "repo": "nixpkgs", - "rev": "62b852f6c6742134ade1abdd2a21685fd617a291", + "rev": "a6531044f6d0bef691ea18d4d4ce44d0daa6e816", "type": "github" }, "original": { - "owner": "NixOS", + "owner": "nixos", "ref": "nixos-unstable", "repo": "nixpkgs", "type": "github" diff --git a/examples/js-es-modules/flake.nix b/examples/js-es-modules/flake.nix index 8c09e37..fb152fe 100644 --- a/examples/js-es-modules/flake.nix +++ b/examples/js-es-modules/flake.nix @@ -32,8 +32,6 @@ es = { enable = true; # This is now default true target = "ts"; # Generate TypeScript by default - generatePackageJson = true; - packageName = "@example/proto"; importExtension = ".js"; # For Node.js ES modules compatibility }; # TypeScript validation support diff --git a/examples/ts-flake-parts/README.md b/examples/ts-flake-parts/README.md index faff1c9..5675929 100644 --- a/examples/ts-flake-parts/README.md +++ b/examples/ts-flake-parts/README.md @@ -204,8 +204,6 @@ The `flake.nix` demonstrates how to integrate Bufrnix with flake-parts: es = { enable = true; target = "ts"; - generatePackageJson = true; - packageName = "@example/proto-ts"; }; connect.enable = true; protovalidate.enable = true; @@ -227,6 +225,8 @@ The `flake.nix` demonstrates how to integrate Bufrnix with flake-parts: } ``` +**Note**: You must manage your own `package.json` file with the appropriate dependencies. See the example `package.json` in this directory. + ## Commands ### Development diff --git a/examples/ts-flake-parts/flake.nix b/examples/ts-flake-parts/flake.nix index edfc735..149c7cc 100644 --- a/examples/ts-flake-parts/flake.nix +++ b/examples/ts-flake-parts/flake.nix @@ -41,8 +41,6 @@ es = { enable = true; target = "ts"; - generatePackageJson = true; - packageName = "@example/proto-ts"; importExtension = ".js"; }; # TypeScript validation support (disabled for now) diff --git a/spectr/changes/remove-es-generatepackagejson/design.md b/spectr/changes/remove-es-generatepackagejson/design.md index 5fb7f88..0e5ac64 100644 --- a/spectr/changes/remove-es-generatepackagejson/design.md +++ b/spectr/changes/remove-es-generatepackagejson/design.md @@ -9,6 +9,7 @@ This document outlines the architectural reasoning for completely removing the ` ### Package.json Generation Locations **1. ES Modules (default.nix)** + ```nix ${optionalString (cfg.es.enable && cfg.es.generatePackageJson) (let esOutputPath = ... @@ -20,6 +21,7 @@ in '' ``` **2. ts-proto (ts-proto.nix)** + ```nix ${optionalString (cfg.generatePackageJson or false) '' cat > ${outputPath}/package.json < in_progress -> completed +// +// Tasks should only move forward through these states. +// Do not skip states or move backward. +// +// Workflow: +// 1. BEFORE starting work on a task, mark it as "in_progress" +// 2. Complete the implementation for the task +// 3. Verify the work is correct and complete +// 4. IMMEDIATELY mark the task as "completed" after verification +// 5. Move to the next task and repeat +// +// IMPORTANT - Update Status Immediately: +// - Update each task's status IMMEDIATELY after it transitions +// - Do NOT batch status updates at the end of all work +// - Do NOT wait until all tasks are done to update statuses +// - This file should reflect accurate progress at any point in time +// - Using a single edit to mark a task completed AND the next task +// in_progress is allowed (this is a single transition, not batching) +// +// Note: This file is auto-generated by 'spectr accept'. Manual edits to +// task status are expected, but structure changes may be overwritten. +// + +{ + "version": 1, + "tasks": [ + { + "id": "1.1", + "section": "Phase 1: Schema and Implementation Removal", + "description": "Remove configuration options from bufrnix-options.nix (js.es.generatePackageJson, js.es.packageName, js.connect.generatePackageJson, js.connect.packageName, js.tsProto.generatePackageJson, js.tsProto.packageName)", + "status": "completed" + }, + { + "id": "1.2", + "section": "Phase 1: Schema and Implementation Removal", + "description": "Remove package.json generation from src/languages/js/default.nix (remove optionalString block from generateHooks)", + "status": "completed" + }, + { + "id": "1.3", + "section": "Phase 1: Schema and Implementation Removal", + "description": "Remove package.json generation from src/languages/js/ts-proto.nix (remove generatePackageJson logic)", + "status": "completed" + }, + { + "id": "1.4", + "section": "Phase 1: Schema and Implementation Removal", + "description": "Check connect.nix for similar changes and remove if needed", + "status": "completed" + }, + { + "id": "2.1", + "section": "Phase 2: Example Projects Update", + "description": "Update examples/js-es-modules/flake.nix (remove generatePackageJson and packageName)", + "status": "completed" + }, + { + "id": "2.2", + "section": "Phase 2: Example Projects Update", + "description": "Create/Update examples/js-es-modules/package.json with proper ES modules configuration", + "status": "completed" + }, + { + "id": "2.3", + "section": "Phase 2: Example Projects Update", + "description": "Update examples/js-es-modules/README.md with migration guidance", + "status": "completed" + }, + { + "id": "2.4", + "section": "Phase 2: Example Projects Update", + "description": "Update examples/ts-flake-parts/flake.nix (remove generatePackageJson and packageName)", + "status": "completed" + }, + { + "id": "2.5", + "section": "Phase 2: Example Projects Update", + "description": "Create/Update examples/ts-flake-parts/package.json with TypeScript configuration", + "status": "completed" + }, + { + "id": "2.6", + "section": "Phase 2: Example Projects Update", + "description": "Update examples/ts-flake-parts/README.md with migration guidance", + "status": "completed" + }, + { + "id": "3.1", + "section": "Phase 3: Documentation Updates", + "description": "Remove generatePackageJson from doc/src/content/docs/reference/configuration.mdx", + "status": "completed" + }, + { + "id": "3.2", + "section": "Phase 3: Documentation Updates", + "description": "Remove generatePackageJson from doc/src/content/docs/reference/languages.mdx", + "status": "completed" + }, + { + "id": "3.3", + "section": "Phase 3: Documentation Updates", + "description": "Remove generatePackageJson from doc/src/content/docs/guides/troubleshooting.mdx", + "status": "completed" + }, + { + "id": "3.4", + "section": "Phase 3: Documentation Updates", + "description": "Create migration guide at doc/src/content/docs/guides/migrating-from-generatepackagejson.mdx", + "status": "completed" + }, + { + "id": "3.5", + "section": "Phase 3: Documentation Updates", + "description": "Update main configuration guide with note about user-managed package.json", + "status": "completed" + }, + { + "id": "4.1", + "section": "Phase 4: Testing and Validation", + "description": "Run ./test-examples.sh to verify no breakage (all 25+ examples pass)", + "status": "completed" + }, + { + "id": "4.2", + "section": "Phase 4: Testing and Validation", + "description": "Run nix fmt and lint to ensure code quality", + "status": "completed" + }, + { + "id": "4.3", + "section": "Phase 4: Testing and Validation", + "description": "Build documentation with cd doc \u0026\u0026 bun run build", + "status": "completed" + }, + { + "id": "4.4", + "section": "Phase 4: Testing and Validation", + "description": "Create git commit with all changes", + "status": "in_progress" + }, + { + "id": "5.1", + "section": "Phase 5: Release and Communication", + "description": "Document breaking change in CHANGELOG", + "status": "pending" + }, + { + "id": "5.2", + "section": "Phase 5: Release and Communication", + "description": "Create GitHub release notes with migration instructions", + "status": "pending" + } + ] +} \ No newline at end of file diff --git a/spectr/changes/remove-es-generatepackagejson/tasks.md b/spectr/changes/remove-es-generatepackagejson/tasks.md deleted file mode 100644 index 53ab515..0000000 --- a/spectr/changes/remove-es-generatepackagejson/tasks.md +++ /dev/null @@ -1,263 +0,0 @@ -# Implementation Tasks: Remove generatePackageJson Feature - -## Task Breakdown - -### Phase 1: Schema and Implementation Removal - -#### Task 1.1: Remove configuration options from bufrnix-options.nix -- **Status**: Pending -- **Description**: Remove the following options from `src/lib/bufrnix-options.nix`: - - `languages.js.es.generatePackageJson` boolean option - - `languages.js.es.packageName` string option - - `languages.js.connect.generatePackageJson` boolean option - - `languages.js.connect.packageName` string option - - `languages.js.tsProto.generatePackageJson` boolean option - - `languages.js.tsProto.packageName` string option -- **Verification**: Run `nix flake check` to ensure schema is valid -- **Duration**: 30 minutes -- **Dependencies**: None - -#### Task 1.2: Remove package.json generation from src/languages/js/default.nix -- **Status**: Pending -- **Description**: - - Remove the `optionalString (cfg.es.enable && cfg.es.generatePackageJson)` block from generateHooks - - Simplify the ES modules initialization and generation logic - - Add comment explaining that package.json should be managed by project -- **Verification**: - - Syntax check with `nix fmt` - - Build check: `nix build .#packages.x86_64-linux.default` -- **Duration**: 20 minutes -- **Dependencies**: Task 1.1 - -#### Task 1.3: Remove package.json generation from src/languages/js/ts-proto.nix -- **Status**: Pending -- **Description**: - - Remove the `optionalString (cfg.generatePackageJson or false)` block from generateHooks - - Remove any references to `cfg.packageName` from package.json template - - Simplify hook logic -- **Verification**: - - Syntax check with `nix fmt` - - Module loads without errors -- **Duration**: 15 minutes -- **Dependencies**: Task 1.1 - -#### Task 1.4: Check connect.nix for similar changes -- **Status**: Pending -- **Description**: - - Review `src/languages/js/connect.nix` - - If it has generatePackageJson logic, remove it following the same pattern - - If it doesn't exist yet, create a note -- **Verification**: Identify if changes needed -- **Duration**: 10 minutes -- **Dependencies**: None - -### Phase 2: Example Projects Update - -#### Task 2.1: Update examples/js-es-modules/flake.nix -- **Status**: Pending -- **Description**: - - Remove `generatePackageJson = true;` from es config - - Remove `packageName = "@example/proto";` from es config - - Keep other ES module configuration intact -- **Verification**: Config syntax valid -- **Duration**: 10 minutes -- **Dependencies**: Task 1.1 - -#### Task 2.2: Create/Update examples/js-es-modules/package.json -- **Status**: Pending -- **Description**: - - Create or update `examples/js-es-modules/package.json` with proper ES modules configuration - - Include @bufbuild/protobuf as dependency - - Ensure "type": "module" is set -- **Verification**: File exists and has valid JSON -- **Duration**: 10 minutes -- **Dependencies**: Task 2.1 - -#### Task 2.3: Update examples/js-es-modules/README.md -- **Status**: Pending -- **Description**: - - Add section explaining that package.json is now user-managed - - Reference migration guide - - Show package.json structure -- **Verification**: Markdown renders correctly -- **Duration**: 10 minutes -- **Dependencies**: Task 2.2 - -#### Task 2.4: Update examples/ts-flake-parts/flake.nix -- **Status**: Pending -- **Description**: - - Remove `generatePackageJson = true;` from es config - - Remove `packageName = "@example/proto-ts";` from es config -- **Verification**: Config syntax valid -- **Duration**: 10 minutes -- **Dependencies**: Task 1.1 - -#### Task 2.5: Create/Update examples/ts-flake-parts/package.json -- **Status**: Pending -- **Description**: - - Create or update `examples/ts-flake-parts/package.json` - - Include proper TypeScript build configuration - - Include Protobuf-ES dependencies -- **Verification**: File exists and has valid JSON -- **Duration**: 10 minutes -- **Dependencies**: Task 2.4 - -#### Task 2.6: Update examples/ts-flake-parts/README.md -- **Status**: Pending -- **Description**: - - Add explanation of user-managed package.json - - Reference migration guide -- **Verification**: Documentation complete -- **Duration**: 10 minutes -- **Dependencies**: Task 2.5 - -### Phase 3: Documentation Updates - -#### Task 3.1: Remove generatePackageJson from reference/configuration.mdx -- **Status**: Pending -- **Description**: - - Search for all instances of `generatePackageJson` in configuration.mdx - - Remove lines showing this option in examples - - Update configuration structure documentation if needed -- **Verification**: - - No remaining references to `generatePackageJson` - - Documentation builds successfully -- **Duration**: 15 minutes -- **Dependencies**: Task 1.1 - -#### Task 3.2: Remove generatePackageJson from reference/languages.mdx -- **Status**: Pending -- **Description**: - - Search for all instances of `generatePackageJson` in languages.mdx - - Remove from all language examples (es, connect, tsProto) - - Remove packageName references -- **Verification**: - - No remaining references to `generatePackageJson` - - Language documentation is still complete -- **Duration**: 15 minutes -- **Dependencies**: Task 1.1 - -#### Task 3.3: Remove generatePackageJson from guides/troubleshooting.mdx -- **Status**: Pending -- **Description**: - - Remove references to generatePackageJson in troubleshooting guide - - Remove packageName examples -- **Verification**: No stale references remain -- **Duration**: 10 minutes -- **Dependencies**: Task 1.1 - -#### Task 3.4: Create migration guide -- **Status**: Pending -- **Description**: - - Create `doc/src/content/docs/guides/migrating-from-generatepackagejson.mdx` - - Document the change and why it was made - - Provide before/after examples - - Show how to create package.json files for different scenarios: - - Protobuf-ES - - ts-proto - - Connect protocol -- **Verification**: - - Guide is comprehensive - - Examples are valid JSON/Nix - - Documentation builds -- **Duration**: 30 minutes -- **Dependencies**: Task 3.1, Task 3.2 - -#### Task 3.5: Update main configuration guide -- **Status**: Pending -- **Description**: - - Review main configuration documentation - - Add note that package.json is user-managed - - Link to migration guide if applicable -- **Verification**: Documentation is accurate -- **Duration**: 10 minutes -- **Dependencies**: Task 3.4 - -### Phase 4: Testing and Validation - -#### Task 4.1: Run test-examples.sh to verify no breakage -- **Status**: Pending -- **Description**: - - Run `./test-examples.sh` to test all 25+ examples - - Verify js-es-modules example works - - Verify ts-flake-parts example works - - Ensure no generated package.json files appear -- **Verification**: - - All examples pass - - No package.json files in generated output -- **Duration**: 45 minutes (depends on system performance) -- **Dependencies**: All previous phases - -#### Task 4.2: Run nix fmt and lint -- **Status**: Pending -- **Description**: - - Run `nix fmt` to ensure all files are properly formatted - - Run `lint` command to check for Nix issues -- **Verification**: - - No formatting issues - - No linting errors -- **Duration**: 10 minutes -- **Dependencies**: All previous phases - -#### Task 4.3: Build documentation -- **Status**: Pending -- **Description**: - - Run `cd doc && bun run build` to build documentation - - Verify no broken links or errors -- **Verification**: - - Documentation builds successfully - - Migration guide is accessible -- **Duration**: 5 minutes -- **Dependencies**: Phase 3 - -#### Task 4.4: Create git commit with all changes -- **Status**: Pending -- **Description**: - - Stage all changes - - Create commit with descriptive message - - Follow project commit conventions - - Reference this change ID in commit message -- **Verification**: - - Commit is successful - - Commit message is clear -- **Duration**: 5 minutes -- **Dependencies**: Task 4.1, 4.2, 4.3 - -### Phase 5: Release and Communication - -#### Task 5.1: Document breaking change in CHANGELOG -- **Status**: Pending (post-implementation) -- **Description**: - - Add entry to CHANGELOG documenting removal - - Note migration path - - Link to migration guide -- **Verification**: CHANGELOG updated -- **Duration**: 10 minutes -- **Dependencies**: Task 4.4 - -#### Task 5.2: Create GitHub release notes -- **Status**: Pending (post-implementation) -- **Description**: - - Prepare release notes highlighting the breaking change - - Include migration instructions - - Mention benefits of the change -- **Duration**: 15 minutes -- **Dependencies**: Task 5.1 - ---- - -## Summary Statistics - -- **Total Tasks**: 25 -- **Estimated Time**: ~4 hours -- **Critical Path**: Task 1.1 → 1.2 → 1.3 → Tests → Commit -- **Parallelizable**: - - Phase 2 tasks can run in parallel (after Task 1.1) - - Phase 3 tasks can run in parallel (after Task 1.1) - - Task 4.1 must run sequentially (depends on all others) - -## Rollout Strategy - -1. **All-at-once**: Complete all tasks in single PR -2. **Rationale**: This is a hard breaking change; better to communicate clearly with one comprehensive update -3. **Release**: Include in next minor version bump with migration guide diff --git a/spectr/changes/remove-ts-proto-generatetsconfig/tasks.jsonc b/spectr/changes/remove-ts-proto-generatetsconfig/tasks.jsonc new file mode 100644 index 0000000..74aa46c --- /dev/null +++ b/spectr/changes/remove-ts-proto-generatetsconfig/tasks.jsonc @@ -0,0 +1,136 @@ +// Spectr Tasks File (JSONC) +// +// This file contains machine-readable task definitions for a Spectr change. +// JSONC format allows comments while maintaining JSON compatibility. +// +// Status Values: +// - "pending" : Task has not been started yet +// - "in_progress" : Task is currently being worked on +// - "completed" : Task has been finished and verified +// +// Status Transitions: +// pending -> in_progress -> completed +// +// Tasks should only move forward through these states. +// Do not skip states or move backward. +// +// Workflow: +// 1. BEFORE starting work on a task, mark it as "in_progress" +// 2. Complete the implementation for the task +// 3. Verify the work is correct and complete +// 4. IMMEDIATELY mark the task as "completed" after verification +// 5. Move to the next task and repeat +// +// IMPORTANT - Update Status Immediately: +// - Update each task's status IMMEDIATELY after it transitions +// - Do NOT batch status updates at the end of all work +// - Do NOT wait until all tasks are done to update statuses +// - This file should reflect accurate progress at any point in time +// - Using a single edit to mark a task completed AND the next task +// in_progress is allowed (this is a single transition, not batching) +// +// Note: This file is auto-generated by 'spectr accept'. Manual edits to +// task status are expected, but structure changes may be overwritten. +// + +{ + "version": 1, + "tasks": [ + { + "id": "2.1", + "section": "Task 1: Remove option definition from bufrnix-options.nix", + "description": "Lines 1080-1084 removed from `src/lib/bufrnix-options.nix`", + "status": "completed" + }, + { + "id": "2.2", + "section": "Task 1: Remove option definition from bufrnix-options.nix", + "description": "No syntax errors when running `nix flake show`", + "status": "completed" + }, + { + "id": "2.3", + "section": "Task 1: Remove option definition from bufrnix-options.nix", + "description": "Schema validation passes: `nix eval .#schemaOutputs` (if applicable)", + "status": "completed" + }, + { + "id": "3.1", + "section": "Task 2: Remove conditional generation block from ts-proto.nix", + "description": "Lines 88-109 removed from `src/languages/js/ts-proto.nix`", + "status": "completed" + }, + { + "id": "3.2", + "section": "Task 2: Remove conditional generation block from ts-proto.nix", + "description": "File syntax valid: `nix eval src/languages/js/ts-proto.nix`", + "status": "completed" + }, + { + "id": "3.3", + "section": "Task 2: Remove conditional generation block from ts-proto.nix", + "description": "No unintended whitespace changes", + "status": "completed" + }, + { + "id": "4.1", + "section": "Task 3: Update documentation in README", + "description": "Example block updated or removed from `examples/js-es-modules/README.md` (lines 142-145)", + "status": "completed" + }, + { + "id": "4.2", + "section": "Task 3: Update documentation in README", + "description": "Markdown syntax valid", + "status": "completed" + }, + { + "id": "4.3", + "section": "Task 3: Update documentation in README", + "description": "Context still makes sense in documentation flow", + "status": "completed" + }, + { + "id": "5.1", + "section": "Task 4: Run test suite", + "description": "`./test-examples.sh` passes completely", + "status": "completed" + }, + { + "id": "5.2", + "section": "Task 4: Run test suite", + "description": "`./check-examples.sh` passes completely", + "status": "completed" + }, + { + "id": "5.3", + "section": "Task 4: Run test suite", + "description": "No generation errors in ts-proto examples", + "status": "completed" + }, + { + "id": "5.4", + "section": "Task 4: Run test suite", + "description": "No errors with `nix fmt` and `lint` commands", + "status": "completed" + }, + { + "id": "6.1", + "section": "Task 5: Validate with openspec", + "description": "`openspec validate remove-ts-proto-generatetsconfig --strict` passes", + "status": "completed" + }, + { + "id": "6.2", + "section": "Task 5: Validate with openspec", + "description": "No specification errors reported", + "status": "completed" + }, + { + "id": "6.3", + "section": "Task 5: Validate with openspec", + "description": "Change is properly formatted", + "status": "completed" + } + ] +} \ No newline at end of file diff --git a/spectr/changes/remove-ts-proto-generatetsconfig/tasks.md b/spectr/changes/remove-ts-proto-generatetsconfig/tasks.md deleted file mode 100644 index 367e210..0000000 --- a/spectr/changes/remove-ts-proto-generatetsconfig/tasks.md +++ /dev/null @@ -1,190 +0,0 @@ -# Tasks: Remove cfg.generateTsConfig from ts-proto.nix - -## Execution Order and Dependencies - -All tasks are **independent** and can be executed in parallel after the initial review. - ---- - -## Task 1: Remove option definition from bufrnix-options.nix - -**Status**: Pending - -**Priority**: High - -**Verification**: -- [ ] Lines 1080-1084 removed from `src/lib/bufrnix-options.nix` -- [ ] No syntax errors when running `nix flake show` -- [ ] Schema validation passes: `nix eval .#schemaOutputs` (if applicable) - -**Changes**: -```nix -// File: src/lib/bufrnix-options.nix -// REMOVE these lines (1080-1084): - generateTsConfig = mkOption { - type = types.bool; - default = false; - description = "Generate tsconfig.json for the generated code"; - }; -``` - -**Notes**: This removes the configuration option from the schema, preventing users from specifying it. - ---- - -## Task 2: Remove conditional generation block from ts-proto.nix - -**Status**: Pending - -**Priority**: High - -**Verification**: -- [ ] Lines 88-109 removed from `src/languages/js/ts-proto.nix` -- [ ] File syntax valid: `nix eval src/languages/js/ts-proto.nix` -- [ ] No unintended whitespace changes - -**Changes**: -```nix -// File: src/languages/js/ts-proto.nix -// REMOVE this entire block (lines 88-109): - # Generate tsconfig.json if needed - ${optionalString (cfg.generateTsConfig or false) '' - cat > ${outputPath}/tsconfig.json < ${esOutputPath}/package.json < ${outputPath}/tsconfig.json < ${outputPath}/package.json <