@grove-dev/starlight 0.2.16 → 0.2.18

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,68 @@
+# Third-party attributions — `@grove-dev/starlight`
+
+This package incorporates design and code from upstream projects. The
+contributions are credited below; reproduction of the upstream license
+texts follows the attribution block. The Grove project ships
+`@grove-dev/starlight` under the same MIT license that the rest of the
+monorepo uses; the third-party license texts below are reproduced here
+to satisfy the upstream attribution requirements.
+
+> **⚠️ TODO(decision): license compatibility check.**
+> The audit and the project's own README credit the upstream work as
+> "lucode / lucas-labs" and reference
+> `https://github.com/lucas-labs/@grove-dev/starlight-theme`. Before the
+> first publish of `@grove-dev/starlight` to npm, the project owner
+> must:
+>
+> 1. Confirm the exact upstream repo URL (the `lucas-labs/...` path
+>    in the README is a placeholder; the real upstream is
+>    `lucode-labs/lucode` or similar — verify on GitHub).
+> 2. Verify the upstream license (MIT? Apache-2.0? something else?)
+>    and confirm it is compatible with the Grove monorepo's MIT
+>    distribution.
+> 3. If compatible, replace the `<!-- TODO LICENSE TEXT -->` block
+>    below with the verbatim upstream license text (most MIT projects
+>    use the standard MIT text — the canonical version is at
+>    <https://opensource.org/licenses/MIT>).
+> 4. If not compatible, either obtain a written license grant from
+>    the upstream maintainer OR replace the derivative design with
+>    original work before publishing.
+>
+> Tracking issue:
+> <https://github.com/tortuvshin/grove/issues/new?title=starlight%3A+verify+third-party+license+compatibility>
+
+## Upstream credits
+
+The design and component overrides in this package derive from:
+
+- **[lucode](https://github.com/lucas-labs/@grove-dev/starlight-theme)** by the
+  **lucas-labs** organization (also referenced as "Lucode" in the
+  package's `user-components.ts` and component overrides). The theme
+  recreates the design of [shadcn/ui](https://ui.shadcn.com/) (MIT)
+  for use inside Astro Starlight, with custom overrides for the
+  header, sidebar, page frame, hero, footer, search, table of
+  contents, pagination, and Markdown content. See the package
+  `README.md` (the "Attribution" and "Usage" sections) for the
+  in-code pointers.
+- **[adrian-ub/starlight-theme-black](https://github.com/adrian-ub/starlight-theme-black)**
+  — the earlier shadcn/ui-inspired Starlight theme that
+  `lucas-labs/@grove-dev/starlight-theme` was based on (per the
+  upstream README).
+- **[shadcn/ui](https://ui.shadcn.com/)** — the original design
+  language that the upstream work and this package both target.
+
+## Upstream license
+
+<!-- TODO LICENSE TEXT: paste the verbatim upstream license (typically
+the standard MIT text with copyright line) here once the license
+compatibility check above is complete. Until then this section is
+intentionally empty so the file can ship without misrepresenting the
+upstream license. -->
+
+## License for this package
+
+`@grove-dev/starlight` is distributed under the **MIT License** — see
+[`../core/LICENSE`](../../LICENSE) at the monorepo root for the
+canonical text. The third-party attributions above are reproduced for
+compliance with the upstream license terms; they do not change the
+license of the rest of the package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grove-dev/starlight",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "type": "module",
   "description": "Grove's theme for Starlight (the Astro native documentation site generator)",
   "author": "grove-dev",
@@ -50,5 +50,8 @@
   "dependencies": {
     "@pagefind/default-ui": "^1.5.2",
     "marked": "^18.0.2"
+  },
+  "scripts": {
+    "test": "cd ../.. && pnpm exec vitest run --project starlight"
   }
 }

package/tests/plugin.test.ts

@@ -0,0 +1,191 @@
+/**
+ * @grove-dev/starlight — config / override / virtual module tests.
+ *
+ * Coverage (per the brief):
+ *   - plugin.ts:parseConfig: accepts empty config (all defaults),
+ *     honours user-supplied fields, throws on invalid input
+ *   - virtual module resolution: the vite plugin's `load` and
+ *     `resolveId` hooks return the canonical module id when
+ *     called with the expected arguments, and pass through for
+ *     unrelated ids
+ *   - override composition: the override() function fills in
+ *     every component override slot, warns the user on a clash,
+ *     and preserves a pre-set user override (does NOT clobber it
+ *     with the default)
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { plugin } from "../core/plugin.js";
+import { override, COMPONENT_OVERRIDES } from "../core/config/override.js";
+import { vitePlugin } from "../core/config/vite.js";
+import { LucodeStarlightConfigSchema } from "../core/config/schemas.js";
+
+describe("parseConfig (exercised through plugin())", () => {
+  it("accepts an empty config and fills in all defaults", () => {
+    // We can't import parseConfig directly (it's local to
+    // plugin.ts), so we exercise it through `plugin(undefined)`,
+    // which goes through the same Zod parse path. The hook
+    // callback is called with the parsed config; we read it
+    // back via the test.
+    let captured: unknown;
+    const p = plugin();
+    // The plugin's `config:setup` hook is the only place
+    // parseConfig's output is consumed. Invoke it with a
+    // minimal stub of the hook parameters and capture the
+    // addIntegration's vite config.
+    const addIntegration = vi.fn();
+    const updateConfig = vi.fn();
+    const calls: Array<{ vite?: { plugins?: Array<{ load?: unknown; resolveId?: unknown }> } }> = [];
+    addIntegration.mockImplementation((integration: { hooks: { "astro:config:setup": (args: { updateConfig: (cfg: { vite?: { plugins?: Array<{ load?: unknown; resolveId?: unknown }> } }) => void }) => void } }) => {
+      integration.hooks["astro:config:setup"]({
+        updateConfig: (cfg) => calls.push(cfg),
+      });
+    });
+    p.hooks["config:setup"]({
+      config: { customCss: [] },
+      logger: { warn: () => {}, info: () => {}, error: () => {}, debug: () => {} } as never,
+      updateConfig: updateConfig as never,
+      addIntegration: addIntegration as never,
+      command: "build" as never,
+      isRestart: false,
+    });
+    expect(calls).toHaveLength(1);
+    const call = calls[0];
+    const vite = call?.vite;
+    expect(vite?.plugins).toBeDefined();
+    captured = vite;
+    // Sanity: parseConfig didn't throw on the empty input.
+    expect(captured).toBeDefined();
+  });
+
+  it("honours user-supplied docs.includeAiUtilities", () => {
+    // Capture the vite plugin's resolved config to assert
+    // that the user's boolean is preserved.
+    let capturedPlugin: ReturnType<typeof vitePlugin> | undefined;
+    const addIntegration = vi.fn((integration: { hooks: { "astro:config:setup": (args: { updateConfig: (cfg: { vite: { plugins: Array<ReturnType<typeof vitePlugin>> } }) => void }) => void } }) => {
+      integration.hooks["astro:config:setup"]({
+        updateConfig: (cfg) => {
+          capturedPlugin = cfg.vite.plugins[0];
+        },
+      });
+    });
+    const p = plugin({ docs: { includeAiUtilities: true } });
+    p.hooks["config:setup"]({
+      config: { customCss: [] },
+      logger: { warn: () => {}, info: () => {}, error: () => {}, debug: () => {} } as never,
+      updateConfig: vi.fn() as never,
+      addIntegration: addIntegration as never,
+      command: "build" as never,
+      isRestart: false,
+    });
+    expect(capturedPlugin).toBeDefined();
+    // The vite plugin's moduleContent embeds the JSON-serialized
+    // config. Load it to confirm `includeAiUtilities: true`
+    // survived the parse.
+    const loaded = capturedPlugin!.load("\0virtual:lucode-starlight-config") as string;
+    expect(loaded).toContain('"includeAiUtilities":true');
+  });
+
+  it("falls back to the schema default for an empty docs object", () => {
+    // The schema has `.default({ includeAiUtilities: false })`
+    // for the docs sub-object. Pin it.
+    const parsed = LucodeStarlightConfigSchema.parse({});
+    expect(parsed.docs?.includeAiUtilities).toBe(false);
+  });
+
+  it("throws on invalid input (zod validation failure)", () => {
+    // A non-string label fails the linkSchema validation.
+    expect(() => LucodeStarlightConfigSchema.parse({ navLinks: "not-an-array" })).toThrow();
+  });
+});
+
+describe("vitePlugin — virtual module resolution", () => {
+  it("resolveId returns the resolved id for the canonical module id", () => {
+    const p = vitePlugin(LucodeStarlightConfigSchema.parse({}));
+    // The virtual module prefix is 'virtual:'. The plugin
+    // matches on the un-prefixed name and returns the
+    // '\0'-prefixed resolved id (Vite convention for virtual
+    // modules — the null byte prevents the resolved id from
+    // being treated as a real file path).
+    const result = p.resolveId?.("virtual:lucode-starlight-config");
+    expect(result).toBe("\0virtual:lucode-starlight-config");
+  });
+
+  it("resolveId returns undefined for unrelated ids (passthrough)", () => {
+    const p = vitePlugin(LucodeStarlightConfigSchema.parse({}));
+    expect(p.resolveId?.("virtual:some-other-module")).toBeUndefined();
+    expect(p.resolveId?.("./relative-import")).toBeUndefined();
+  });
+
+  it("load returns the JSON-serialized config when given the resolved id", () => {
+    const config = LucodeStarlightConfigSchema.parse({ docs: { includeAiUtilities: true } });
+    const p = vitePlugin(config);
+    const module = p.load?.("\0virtual:lucode-starlight-config") as string;
+    expect(module).toContain("export default");
+    expect(module).toContain('"includeAiUtilities":true');
+  });
+
+  it("load returns undefined for unrelated ids", () => {
+    const p = vitePlugin(LucodeStarlightConfigSchema.parse({}));
+    expect(p.load?.("not-the-virtual-id")).toBeUndefined();
+  });
+});
+
+describe("override — component override composition", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  it("fills every component override slot when the user has none", () => {
+    // Starlight starts with no components overridden (empty
+    // config). The override() function should set every key in
+    // COMPONENT_OVERRIDES to point at the @grove-dev/starlight
+    // path.
+    const components = override(
+      { components: {} } as never,
+      COMPONENT_OVERRIDES,
+      { warn: warnSpy, info: () => {}, error: () => {}, debug: () => {} } as never,
+    );
+    for (const key of COMPONENT_OVERRIDES) {
+      expect(components?.[key]).toBe(`@grove-dev/starlight/components/overrides/${key}.astro`);
+    }
+  });
+
+  it("preserves a user-supplied component override (does not clobber)", () => {
+    // If the user already set components.Footer, we should
+    // NOT overwrite it with the default — we warn and skip.
+    // Pin: a previous "always overwrite" implementation would
+    // silently clobber the user's custom footer.
+    const userFooter = "./my-custom/Footer.astro";
+    const components = override(
+      { components: { Footer: userFooter } } as never,
+      COMPONENT_OVERRIDES,
+      { warn: warnSpy, info: () => {}, error: () => {}, debug: () => {} } as never,
+    );
+    expect(components?.Footer).toBe(userFooter);
+    // The warn call names the slot and points at the override path.
+    const warnings = warnSpy.mock.calls.map((c: unknown[]) => String(c[0]));
+    expect(warnings.some((w: string) => w.includes("Footer"))).toBe(true);
+    // All OTHER slots are still filled in.
+    expect(components?.Header).toBe(`@grove-dev/starlight/components/overrides/Header.astro`);
+  });
+
+  it("handles a config with no `components` field at all (undefined)", () => {
+    // Defensive: Starlight's config can omit `components`
+    // entirely. override() should still produce a full set
+    // without throwing.
+    const components = override(
+      {} as never,
+      COMPONENT_OVERRIDES,
+      { warn: warnSpy, info: () => {}, error: () => {}, debug: () => {} } as never,
+    );
+    for (const key of COMPONENT_OVERRIDES) {
+      expect(components?.[key]).toBeDefined();
+    }
+  });
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true,
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["core/**/*.ts", "tests/**/*.ts", "global.d.ts", "virtual.d.ts", "index.ts", "schema.ts", "user-components.ts"]
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Turtuvshin Byambaa
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.