alexion
220f73d8f7
Sets up the initial project structure: two packages (@kitchen-md/core and @kitchen-md/bin), shared tsconfig, shared fixtures, per-package test stubs (unit, integration, smoke), .gitignore, and project CLAUDE.md with Conventional Commits convention.
64 lines
4.7 KiB
Markdown
64 lines
4.7 KiB
Markdown
## Problem Statement
|
|
|
|
The `kitchen-md` repository is a fresh git init with no files.
|
|
Before any implementation can begin, the project needs a complete structural scaffold: a monorepo layout, two packages, TypeScript configuration, and a testing infrastructure organised by tier.
|
|
|
|
## Solution
|
|
|
|
A Bun-workspaces monorepo containing two packages (`@kitchen-md/core` and `@kitchen-md/bin`), a shared TypeScript base configuration, and per-package test scaffolding organised into unit, integration, and smoke tiers.
|
|
Synthetic test fixtures are shared at the workspace root so both packages can reference the same canonical recipe files.
|
|
|
|
## User Stories
|
|
|
|
1. As a developer, I want a Bun workspace root so that I can manage both packages with a single toolchain and no additional runtime.
|
|
2. As a developer, I want `@kitchen-md/core` isolated as its own package so that it can be consumed by a future Obsidian plugin without bundling the CLI.
|
|
3. As a developer, I want `@kitchen-md/bin` isolated as its own package so that the CLI binary can be compiled and distributed independently of the library.
|
|
4. As a developer, I want a shared TypeScript base configuration at the workspace root so that both packages inherit consistent compiler settings without duplication.
|
|
5. As a developer, I want unit test files co-located with their source module so that the test for a module is always findable next to the module itself.
|
|
6. As a developer, I want integration test files co-located with the code they exercise so that cross-module test coverage is discoverable alongside the relevant source.
|
|
7. As a developer, I want smoke tests in `@kitchen-md/bin` that invoke the CLI directly so that end-to-end user-story coverage is separated from unit-level coverage.
|
|
8. As a developer, I want synthetic recipe fixture files at the workspace root so that both packages can reference the same canonical test inputs without duplication.
|
|
|
|
## Implementation Decisions
|
|
|
|
- Bun is the single toolchain for the entire project: package manager, runtime, test runner, and native binary compiler (`bun --compile`).
|
|
No Node.js runtime is required on target machines.
|
|
- The workspace root `package.json` declares Bun workspaces pointing to `packages/core` and `packages/bin`.
|
|
- `@kitchen-md/core` lives in `packages/core/` and is structured as a publishable library with a single entry point.
|
|
- `@kitchen-md/bin` lives in `packages/bin/`, declares `@kitchen-md/core` as a workspace dependency, and declares a `bin` entry named `kitchen` pointing at the CLI entry point.
|
|
- A `tsconfig.json` at the workspace root defines shared compiler settings (strict mode, ESNext target and module, bundler module resolution, Bun types).
|
|
Each package's `tsconfig.json` extends the root config.
|
|
- A `fixtures/` directory at the workspace root holds synthetic `.md` recipe files.
|
|
The primary fixture covers every annotation type (ingredient, cookware, timer) and all format features.
|
|
Additional fixture files are acceptable for regression cases or edge cases that cannot fit cleanly into the primary file.
|
|
|
|
## Testing Decisions
|
|
|
|
- Tests assert external behaviour only — given an input, assert the output — never implementation internals.
|
|
- **Unit tests**: co-located with the source file they test, named `{module}_test.ts`.
|
|
All test data is inline raw strings within the test file; no filesystem access.
|
|
Both packages have unit tests.
|
|
- **Integration tests**: co-located with the source they exercise, naming is flexible.
|
|
Integration tests read from the shared `fixtures/` directory.
|
|
Both packages have integration tests where they cross file boundaries.
|
|
- **Smoke tests**: present only in `@kitchen-md/bin`.
|
|
Each smoke test invokes the CLI directly (via subprocess or equivalent) and asserts its output against expected results.
|
|
Smoke tests use the shared `fixtures/` directory as input.
|
|
Smoke test coverage maps directly to the CLI user stories in the recipe format spec.
|
|
- The Bun test runner discovers test files via `*_test.ts` and `*.test.ts` patterns; all test files must match one of these patterns to be picked up automatically.
|
|
|
|
## Out of Scope
|
|
|
|
- Parser implementation (covered by the recipe format spec).
|
|
- CLI command design and subcommand structure.
|
|
- Aisle mapping file format.
|
|
- Shopping list generator.
|
|
- Publishing either package to a registry.
|
|
- CI/CD configuration.
|
|
|
|
## Further Notes
|
|
|
|
- The `$` sigil for cookware and the choice of Bun over other runtimes are decisions from the recipe format spec; this scaffold spec assumes them and does not re-litigate them.
|
|
- The binary is named `kitchen` (the `bin` key in `@kitchen-md/bin`'s `package.json`), not `kitchen-md` or `kmd`.
|
|
- Smoke tests differ from integration tests in degree, not kind: they test the CLI as a black box from the outside rather than testing module interactions from the inside.
|