@augeo/smelt 1.2.2

package/docs/TESTING.md

@@ -0,0 +1,293 @@
+# Testing
+
+Conventions for writing tests in Smelt. Most of this is project-agnostic
+guidance adapted from [betterspecs.org](https://www.betterspecs.org/) and
+[bettertests.js.org](https://bettertests.js.org/).
+
+The test runner is [Vitest](https://vitest.dev/) in Browser Mode via
+[`@augeo/assay`](https://www.npmjs.com/package/@augeo/assay). Tests run against
+the **built** theme directories (`sections/`, `snippets/`, `blocks/`), since
+assay / LiquidJS cannot resolve the `@/...` source alias.
+
+- [Describe Your Files](#describe-your-files)
+  - [When the Filename Doesn't Match the Exports / Multiple Exports](#when-the-filename-doesnt-match-the-exports--multiple-exports)
+- [Nest Describes to Add Context](#nest-describes-to-add-context)
+- [Use `it` to Describe the Expected Behavior](#use-it-to-describe-the-expected-behavior)
+- [Single Expectation Tests](#single-expectation-tests)
+- [Use Subjects](#use-subjects)
+- [Before / After Hooks Should Be Single Concern](#before--after-hooks-should-be-single-concern)
+- [Don't Use 'should'](#dont-use-should)
+- [Describe the Expected Behavior / What the User Will See](#describe-the-expected-behavior--what-the-user-will-see)
+- [Use Factories](#use-factories)
+- [When to Mock](#when-to-mock)
+- [Inspiration](#inspiration)
+
+## Describe Your Files
+
+Usually a file should have a single named export that's named the same as the
+containing file. In this case your root `describe` should be the exported
+object.
+
+#### Bad
+
+```ts
+describe("a Hamburger Menu component", () => {});
+describe("a function that describes sandwiches", () => {});
+describe("a constant holding our ingredients", () => {});
+```
+
+#### Good
+
+```ts
+describe("<HamburgerMenu />", () => {});
+describe("describeSandwiches()", () => {});
+describe("ingredients", () => {});
+```
+
+For Liquid components, name the describe after the component file:
+
+```ts
+describe("button.liquid", () => {});
+describe("hero.liquid", () => {});
+```
+
+### When the Filename Doesn't Match the Exports / Multiple Exports
+
+If you have multiple exports in a file or the file name doesn't match the export
+name, use a root-level describe for the file that's as short as possible while
+still being descriptive, then nest describes per export.
+
+#### Bad
+
+```ts
+describe("addPickles()", () => {});
+describe("removePickles()", () => {});
+```
+
+#### Good
+
+```ts
+describe("pickleManager", () => {
+	describe("addPickles()", () => {});
+	describe("removePickles()", () => {});
+});
+```
+
+## Nest Describes to Add Context
+
+Use nested describes to add context — they keep tests clear and well organized.
+When describing a context, start its description with `when`, `as`, `with`, or
+`without`.
+
+Nested describes are also useful to group tests that share setup or mock
+requirements. `beforeEach` is preferred for isolation; reach for `beforeAll`
+only when setup is expensive.
+
+#### Bad
+
+```ts
+it("shows order details when logged in", () => {});
+it("redirects to login when logged out", () => {});
+```
+
+#### Good
+
+```ts
+describe("when logged in", () => {
+	beforeEach(setupValidSession);
+
+	it("shows order details", () => {});
+});
+
+describe("when logged out", () => {
+	beforeEach(setupInvalidSession);
+
+	it("redirects to login", () => {});
+});
+```
+
+## Use `it` to Describe the Expected Behavior
+
+#### Bad
+
+```ts
+test("constructs a sandwich", () => {});
+```
+
+#### Good
+
+```ts
+it("constructs a sandwich", () => {});
+```
+
+## Single Expectation Tests
+
+Each test should specify one (and only one) behavior. Multiple expectations in
+the same test usually signal you're specifying multiple behaviors — but there
+are cases where multiple expectations support a single behavior.
+
+When a test fails, it should be immediately clear what behavior is broken.
+
+#### Bad
+
+```ts
+it("renders the product card", async () => {
+	await render("product-card", { product });
+
+	await expect.element(page.getByText("Classic Tee")).toBeVisible();
+	await expect.element(page.getByText("$29.99")).toBeVisible();
+});
+```
+
+#### Good
+
+```ts
+describe("content", () => {
+	beforeEach(() => render("product-card", { product }));
+
+	it("shows the product title", async () => {
+		await expect.element(page.getByText("Classic Tee")).toBeVisible();
+	});
+
+	it("shows the formatted price", async () => {
+		await expect.element(page.getByText("$29.99")).toBeVisible();
+	});
+});
+```
+
+Multiple expectations supporting one behavior are fine:
+
+```ts
+it("formats discounts", async () => {
+	// Both expectations describe one behavior: the discount styling.
+	await expect.element(page.getByText("Sale")).toHaveClass("discount");
+	await expect.element(page.getByText("Sale")).not.toHaveClass("full-price");
+});
+```
+
+## Use Subjects
+
+If you have several tests related to the same subject, use a `describe` block to
+DRY them up.
+
+#### Bad
+
+```ts
+it("shows the title", async () => {
+	await render("product-card", { product: { title: "Clubhouse" } });
+	await expect.element(page.getByText("Clubhouse")).toBeVisible();
+});
+
+it("shows the description", async () => {
+	await render("product-card", { product: { title: "Clubhouse" } });
+	await expect.element(page.getByText("A delicious sandwich")).toBeVisible();
+});
+```
+
+#### Good
+
+```ts
+describe("content", () => {
+	beforeEach(() => render("product-card", { product: { title: "Clubhouse" } }));
+
+	it("shows the title", async () => {
+		await expect.element(page.getByText("Clubhouse")).toBeVisible();
+	});
+
+	it("shows the description", async () => {
+		await expect.element(page.getByText("A delicious sandwich")).toBeVisible();
+	});
+});
+```
+
+## Before / After Hooks Should Be Single Concern
+
+Lifecycle hooks should each relate to a single concern. Biome's
+`noDuplicateTestHooks` rule is disabled in `biome.json` to allow this pattern.
+
+#### Bad
+
+```ts
+describe("with lettuce", () => {
+	beforeEach(() => {
+		sandwich.addLettuce();
+		restaurant.build(sandwich);
+	});
+});
+```
+
+#### Good
+
+```ts
+describe("with lettuce", () => {
+	beforeEach(() => sandwich.addLettuce());
+	beforeEach(() => restaurant.build(sandwich));
+});
+```
+
+## Don't Use 'should'
+
+Don't use "should" when describing tests. Use the third person, present tense.
+
+#### Bad
+
+```ts
+it("should return a sandwich", () => {});
+```
+
+#### Good
+
+```ts
+it("returns a sandwich", () => {});
+```
+
+## Describe the Expected Behavior / What the User Will See
+
+Describe and test the expected behavior, not implementation details. See
+[Testing Library's guiding principles](https://testing-library.com/docs/guiding-principles).
+
+#### Bad
+
+```ts
+it("fetches order from the DB", () => {});
+it("calls 'showToast'", () => {});
+```
+
+#### Good
+
+```ts
+it("returns the order's details", () => {});
+it("shows a success message", () => {});
+```
+
+## Use Factories
+
+Don't use fixtures — they're hard to control. Use factories instead to reduce
+verbosity when creating test data.
+
+## When to Mock
+
+Don't overuse mocks. They're useful when you need to isolate the interface of a
+dependency. In a strongly-typed language, type-checking already gives you a lot
+of that confidence — calling through to the real implementation is often fine
+when it's cheap.
+
+That said, asserting that a dependency was called (rather than relying on its
+side effects) can be valuable: it decouples your test from the dependency's
+implementation.
+
+> Mock-based tests are more coupled to the interfaces in your system, while
+> classical tests are more coupled to the implementation of an object's
+> collaborators.
+>
+> —
+> [Thoughts on Mocking](https://web.archive.org/web/20220612005103/http://myronmars.to/n/dev-blog/2012/06/thoughts-on-mocking)
+
+For mocking nested `{% render %}` calls in Liquid tests, see the
+[`@augeo/assay` mocking docs](https://github.com/seanhealy/assay/blob/main/docs/advanced-usage.md#mocking).
+
+## Inspiration
+
+Most of this guidance comes from [betterspecs.org](https://www.betterspecs.org/)
+— written for RSpec but a great guide for tests in general. Some additional
+guidance from [bettertests.js.org](https://bettertests.js.org/).

package/docs/assets-plan.md

@@ -0,0 +1,197 @@
+---
+status: draft
+---
+
+# Component-Owned Assets
+
+Plan for letting a component own colocated binary assets (PNG, JPG, WebP, WOFF2,
+anything that has to be a real file at a Shopify-resolvable URL). Companion to
+[`build-spec.md`](./build-spec.md) — the build spec describes today's behavior;
+this doc describes the shape and decisions for adding asset emission.
+
+## Goal
+
+A consumer authoring an icon component should be able to put a `cart.png` next
+to `icon.liquid` and reference it from Liquid without leaving the component
+directory or mangling Shopify-flat asset names by hand. Layering should apply to
+assets the same way it does to every other slot: a consumer dropping in a
+same-named PNG shadows the baseline's.
+
+Today the spec says `assets/` is "entirely hand-written in v1" — this plan flips
+that constraint.
+
+## The authoring shape
+
+A component opts into asset emission by adding an `assets/` subdirectory:
+
+```
+src/components/icon/
+├── icon.liquid
+├── icon.css
+└── assets/
+    ├── cart.png
+    ├── search.png
+    └── menu.png
+```
+
+Build copies each file to:
+
+```
+assets/built--components--icon--cart.png
+assets/built--components--icon--search.png
+assets/built--components--icon--menu.png
+```
+
+The author writes assets the standard Shopify way — `asset_url` filter, the
+output landing in the flat `assets/` directory the storefront actually serves
+from.
+
+## Design Decisions
+
+### 1. Per-component `assets/` subdir, not loose siblings
+
+A component's assets live under a dedicated `assets/` subdir, not as bare files
+next to `<name>.liquid`.
+
+- **Why:** explicit signal. The build doesn't have to guess "is this `.png` an
+  asset or some slot we haven't defined yet?" The convention is discoverable
+  from a single `ls` of the component directory.
+- **Cost:** one extra directory level in source. Worth it for the clarity.
+
+### 2. Output naming reuses `built--<segments>--<filename>`
+
+Same naming scheme as snippets/sections/blocks, just landing in `assets/`
+instead of `sections/` / `snippets/` / `blocks/`. The final segment is the
+asset's own filename (including extension), not the source component's directory
+name.
+
+- **Why:** consistency. The cleanup sweep, the prefix discipline, and the
+  layering keying all already work this way. No new naming convention to
+  remember.
+- **Cost:** asset names are verbose (`built--components--icon--cart.png`), which
+  is exactly the ergonomics gap the alias rewriter below closes.
+
+### 3. Cleanup extends to `assets/`
+
+The build's existing clean step sweeps `/^_?built--/` from `sections/`,
+`snippets/`, and `blocks/`. Add `assets/` to that list — anything starting with
+`built--` in the consumer's `assets/` directory gets cleaned and rewritten on
+every build. Hand-written files without the prefix survive.
+
+- **Why:** same additive-build guarantee that everywhere else honors. Removed
+  source assets disappear cleanly; hand-authored `assets/background.jpg` is
+  untouched.
+- **Cost:** none meaningful. `assets/` is currently a do-not-touch zone; this
+  scopes the touch to the reserved prefix.
+
+### 4. Layering applies to assets
+
+If both consumer and baseline have `src/components/icon/assets/cart.png`,
+first-wins like every other slot. The consumer's PNG wins; the baseline's is
+ignored.
+
+- **Why:** consistent with how every other file resolves through the layer list.
+  A consumer can override a single icon by dropping a same-named PNG into their
+  tree.
+- **Cost:** none. The resolver gets an extra slot to track, but the rule is the
+  rule.
+
+### 5. Single-pass alias rewriter (broader than today)
+
+The existing rewriter only matches `'@/...'` and `'./...'` strings inside
+`{% render %}` / `{% include %}` tags. To make asset references ergonomic
+(`{{ '@/components/icon/assets/cart.png' | asset_url }}` instead of the mangled
+`'built--components--icon--cart.png'`), the rewriter pass extends to **any
+string literal containing an `@/` or `./` alias.**
+
+The rule is: in every `.liquid` source file, find every `'@/...'` or `'./...'`
+string literal, resolve it against the lookup map, replace it with the built
+name. If a path doesn't resolve, error with file + line.
+
+- **Why:** the realistic rate of false positives approaches zero. A `'@/...'`
+  string in a Liquid source file is almost certainly a Smelt alias — meaningless
+  to Shopify on its own. Considered and rejected: a separate `@asset/` alias
+  (splits the mental model), filter-context detection (allowlist of `asset_url`
+  / `asset_img_url` / etc. — narrow on purpose but more fragile than the simpler
+  design), and a catch-all validator (unnecessary if the rewriter is broad).
+- **Cost:** a typo today silently passes through to runtime and Shopify fails
+  confusingly; with the broader rewriter it becomes a clean build-time error
+  pointing at the line. That's a behavior change — but an improvement, not a
+  regression. The other cosmetic case (a comment that happens to mention
+  `'@/components/button'` gets rewritten) is dead text in the output and doesn't
+  break anything.
+
+## Out of Scope
+
+Things this plan deliberately does not address:
+
+- **Transforms.** No image resizing, format conversion, or quality knobs. Just
+  copy. If we want a pipeline like Vite's image plugins, that's its own design
+  discussion.
+- **Cache-busting / content hashing.** Shopify's CDN handles its own cache key
+  strategy from the asset URL. We don't append `?v=hash` or rename to
+  `built--…-abc123.png`.
+- **Schema / metadata for assets.** No `<name>.schema.ts` equivalent — assets
+  are dumb files, not authoring artifacts that need types.
+- **Asset-only "components."** A directory containing only `assets/` and no
+  `.liquid` is not a component. The build still requires a `.liquid` anchor to
+  register a component; assets are slots of an existing component.
+
+## Implementation Outline
+
+A concrete-but-not-final list of where changes land:
+
+1. **`lib/resolver.ts`** — recognize each component's `assets/` subdir as a new
+   slot. Likely `assets?: ComponentSource[]` on `ResolvedComponent` (plural —
+   components can have many assets). Walk happens at the same time as the
+   other-slots resolution.
+2. **`lib/build/build.ts`**
+   - **`cleanBuiltOutputs`** — add `assets` to `TYPE_TO_OUTPUT_DIRECTORY`'s
+     sweep targets (or maintain a separate cleanup-roots list — see Open
+     Questions).
+   - **`buildComponent`** — for each asset in the component, copy from
+     `component.assets[i].path` to
+     `assets/built--<component.segments.join("--")>--<filename>`. Stream the
+     file rather than read-into-memory if it gets large.
+   - **`rewriteRenders`** — generalize to walk any `'@/...'` / `'./...'` string
+     in the source. Rename to `rewriteLiquidAliases` (or similar). The
+     render-tag-specific regex becomes a broader one. Existing render rewrites
+     continue to work because they're a subset.
+   - **`lookup`** — needs to contain asset entries too, so the rewriter can
+     resolve `'@/components/icon/assets/cart.png'` to its built name. Key shape
+     needs thought — assets are not just segments-joined; they have filenames
+     with extensions.
+3. **`docs/build-spec.md`**
+   - Remove `assets/` from the "build does not read or write" list.
+   - Document the `assets/` subdir convention.
+   - Update Output Naming section with the asset case.
+   - Update the alias-rewriter description to reflect the broader scope.
+4. **`example/`** — add a small demonstration. An icon component with one or two
+   PNGs is the canonical use case. Verify it builds, theme-check passes, and the
+   asset_url renders correctly via assay browser tests.
+5. **Tests** — extend `lib/build/build.test.ts` with:
+   - Asset emission to `assets/built--...`
+   - Cleanup of removed assets
+   - Layering (consumer shadows baseline)
+   - Alias rewrite in non-render contexts (`{{ '@/...' | asset_url }}`)
+   - Unresolved alias → build error
+
+## Open Questions
+
+- **Lookup map keying.** Today the lookup is
+  `segments.join("/") → ResolvedComponent`. For assets, we'd want
+  `<component-segments>/assets/<filename>` to resolve directly. Either add asset
+  entries to the same map with a different key shape, or maintain a parallel
+  map. Probably the former, but worth confirming during implementation.
+- **Sub-paths under `assets/`.** Should `assets/icons/cart.png` work, with the
+  built name being `built--components--icon--icons--cart.png`? Or do we require
+  a flat `assets/` directory? Flat is simpler; nested mirrors the existing
+  component-tree freedom. Probably allow nesting; cost is small.
+- **Other-extension overlap.** A consumer with a `cart.png` and a `cart.svg` in
+  the same `assets/` directory — both copy fine, no conflict. But if someone
+  puts a `.liquid` in `assets/`, what happens? Defining "assets are not liquid"
+  by convention is cleanest; the build could ignore `.liquid` in `assets/` or
+  error. Defer.
+- **`utilities/assets/`?** Could a utility module have its own assets? The spec
+  already says utilities have no Liquid output. Extending assets to utilities
+  would be possible but probably not worth the complexity for the first cut.