@levino/shipyard-base 0.9.2 → 0.9.3-rc-20260926183647

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levino/shipyard-base",
-  "version": "0.9.2",
+  "version": "0.9.3-rc-20260926183647",
   "description": "Core layouts, components, and configuration for shipyard - a composable page builder for Astro",
   "keywords": [
     "astro",
@@ -60,20 +60,21 @@
     "remark-html": "^16.0.1",
     "tailwindcss": "^4",
     "typescript": "^7.0.2",
-    "vite": "^8.2.2",
-    "vitest": "^4.1.11"
+    "vite": "^8.3.1",
+    "vitest": "^5.0.2"
   },
   "dependencies": {
-    "@astrojs/markdown-remark": "^7.2.4",
-    "clsx": "^2.1.0",
-    "mdast-util-directive": "^3.0.0",
+    "@astrojs/markdown-remark": "^7.3.1",
+    "@astrojs/markdown-satteri": "^0.4.2",
+    "clsx": "^2.1.1",
+    "mdast-util-directive": "^3.1.0",
     "mdast-util-to-hast": "^13.2.1",
-    "micromark-extension-directive": "^3.0.0",
+    "micromark-extension-directive": "^4.0.0",
     "ramda": "^0.32.0",
-    "remark-directive": "^3.0.0",
+    "remark-directive": "^4.0.0",
     "remark-parse": "^11.0.0",
-    "tailwind-merge": "^2.2.0",
-    "unified": "^11.0.0",
-    "unist-util-visit": "^5.0.0"
+    "tailwind-merge": "^3.7.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0"
   }
 }

package/src/index.ts

@@ -1,9 +1,6 @@
 import { fileURLToPath } from 'node:url'
-import { isUnifiedProcessor, unified } from '@astrojs/markdown-remark'
 import type { AstroIntegration } from 'astro'
-import { remarkAdmonitions } from './remark/remarkAdmonitions'
-import { remarkBlockDirective } from './remark/remarkBlockDirective'
-import { remarkNpm2Yarn } from './remark/remarkNpm2Yarn'
+import { shipyardMarkdownProcessor } from './markdownProcessor'
 import type { Config } from './schemas/config'
 import { checkLinks, reportBrokenLinks } from './tools/linkChecker'
 
@@ -46,38 +43,13 @@ export default (config: Config): AstroIntegration => {
           [shipyardCssId]: config.css ? `import '${config.css}';` : '',
         } as Record<string, string | undefined>
 
-        // Astro 7 renders Markdown with Sätteri by default, which does not run
-        // unified plugins. shipyard's admonitions, npm2yarn tabs and block
-        // directives are all remark plugins, so we pin the unified processor
-        // from @astrojs/markdown-remark. Any plugins the user already put on
-        // their own `unified()` processor are carried over so both sets run;
-        // plugins they pass via the deprecated `markdown.remarkPlugins` option
-        // are appended by Astro afterwards.
-        const userProcessor = astroConfig.markdown?.processor
-        const inherited =
-          userProcessor && isUnifiedProcessor(userProcessor)
-            ? userProcessor.options
-            : undefined
-
-        if (userProcessor && !inherited) {
-          logger.warn(
-            `\`markdown.processor\` is set to \`${userProcessor.name}\`, which does not run remark plugins. ` +
-              'Overriding it with `unified()` so shipyard admonitions, npm2yarn tabs and block directives keep working.',
-          )
-        }
+        const processor = shipyardMarkdownProcessor(
+          astroConfig.markdown.processor,
+          logger,
+        )
 
         updateConfig({
-          markdown: {
-            processor: unified({
-              ...inherited,
-              remarkPlugins: [
-                ...(inherited?.remarkPlugins ?? []),
-                remarkBlockDirective,
-                remarkAdmonitions,
-                remarkNpm2Yarn,
-              ],
-            }),
-          },
+          ...(processor && { markdown: { processor } }),
           vite: {
             plugins: [
               {

package/src/markdownProcessor.test.ts

@@ -1,6 +1,12 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import type { UnifiedResolvedOptions } from '@astrojs/markdown-remark'
 import { unified } from '@astrojs/markdown-remark'
-import { describe, expect, test, vi } from 'vitest'
+import { satteri } from '@astrojs/markdown-satteri'
+import type { AstroConfig, AstroInlineConfig } from 'astro'
+import { sync } from 'astro'
+import { afterEach, describe, expect, test, vi } from 'vitest'
 import shipyard from './index'
 import type { Config } from './schemas/config'
 
@@ -23,8 +29,11 @@ const baseConfig: Config = {
 /**
  * Runs the integration's `astro:config:setup` hook against a fake Astro config
  * and returns whatever it passed to `updateConfig`, plus the logger it used.
+ * Without a processor, the config gets Astro's default, as resolution does.
  */
-const runConfigSetup = (astroConfig: Record<string, unknown> = {}) => {
+const runConfigSetup = (
+  processor: { name: string; options: object } = satteri(),
+) => {
   const updates: ConfigUpdate[] = []
   const logger = { warn: vi.fn(), info: vi.fn(), error: vi.fn() }
 
@@ -34,7 +43,7 @@ const runConfigSetup = (astroConfig: Record<string, unknown> = {}) => {
 
   hook({
     updateConfig: (update: ConfigUpdate) => updates.push(update),
-    config: astroConfig,
+    config: { markdown: { processor } },
     logger,
   } as never)
 
@@ -42,13 +51,14 @@ const runConfigSetup = (astroConfig: Record<string, unknown> = {}) => {
 }
 
 describe('markdown processor', () => {
-  test('pins the unified processor so remark plugins run under Astro 7', () => {
-    const { update } = runConfigSetup()
+  test("replaces Astro's default processor with unified, without a warning", () => {
+    const { update, logger } = runConfigSetup()
 
     expect(update?.markdown?.processor?.name).toBe(unified().name)
     expect(update?.markdown?.processor?.options.remarkPlugins).toHaveLength(
       SHIPYARD_PLUGIN_COUNT,
     )
+    expect(logger.warn).not.toHaveBeenCalled()
   })
 
   test('does not use the deprecated markdown.remarkPlugins option', () => {
@@ -59,9 +69,9 @@ describe('markdown processor', () => {
 
   test("keeps the user's own plugins on an existing unified processor", () => {
     const userPlugin = () => undefined
-    const { update, logger } = runConfigSetup({
-      markdown: { processor: unified({ remarkPlugins: [userPlugin] }) },
-    })
+    const { update, logger } = runConfigSetup(
+      unified({ remarkPlugins: [userPlugin] }),
+    )
 
     const plugins = update?.markdown?.processor?.options.remarkPlugins
     expect(plugins).toHaveLength(SHIPYARD_PLUGIN_COUNT + 1)
@@ -70,24 +80,90 @@ describe('markdown processor', () => {
   })
 
   test("carries over the user's other unified options", () => {
-    const { update } = runConfigSetup({
-      markdown: { processor: unified({ gfm: false, smartypants: false }) },
-    })
+    const { update } = runConfigSetup(
+      unified({ gfm: false, smartypants: false }),
+    )
 
     expect(update?.markdown?.processor?.options.gfm).toBe(false)
     expect(update?.markdown?.processor?.options.smartypants).toBe(false)
   })
 
-  test('warns and overrides when a non-unified processor is configured', () => {
-    const { update, logger } = runConfigSetup({
-      markdown: { processor: { name: 'satteri', options: {} } },
-    })
+  test('leaves a configured satteri processor alone and warns', () => {
+    const { update, logger } = runConfigSetup(
+      satteri({ features: { directive: true } }),
+    )
 
+    expect(update).not.toHaveProperty('markdown')
     expect(logger.warn).toHaveBeenCalledOnce()
     expect(logger.warn.mock.calls[0]?.[0]).toContain('satteri')
-    expect(update?.markdown?.processor?.name).toBe(unified().name)
-    expect(update?.markdown?.processor?.options.remarkPlugins).toHaveLength(
-      SHIPYARD_PLUGIN_COUNT,
+  })
+
+  test('leaves any other configured processor alone and warns', () => {
+    const { update, logger } = runConfigSetup({ name: 'custom', options: {} })
+
+    expect(update).not.toHaveProperty('markdown')
+    expect(logger.warn).toHaveBeenCalledOnce()
+    expect(logger.warn.mock.calls[0]?.[0]).toContain('custom')
+  })
+})
+
+describe('markdown processor with the real Astro config', () => {
+  let root: string | undefined
+
+  afterEach(async () => {
+    vi.restoreAllMocks()
+    if (root) await rm(root, { recursive: true, force: true })
+  })
+
+  const resolveWithAstro = async (
+    configured?: NonNullable<AstroInlineConfig['markdown']>['processor'],
+  ) => {
+    root = await mkdtemp(join(tmpdir(), 'shipyard-markdown-'))
+    // Astro's console logger sends warnings to `console.info`, errors to `console.error`.
+    const output = [
+      vi.spyOn(console, 'info').mockImplementation(() => {}),
+      vi.spyOn(console, 'error').mockImplementation(() => {}),
+    ]
+    let processor: AstroConfig['markdown']['processor'] | undefined
+
+    await sync({
+      root,
+      markdown: configured ? { processor: configured } : {},
+      logger: { entrypoint: 'astro/logger/console' },
+      integrations: [
+        shipyard(baseConfig),
+        {
+          name: 'processor-probe',
+          hooks: {
+            'astro:config:done': ({ config }) => {
+              processor = config.markdown.processor
+            },
+          },
+        },
+      ],
+    })
+
+    const shipyardWarnings = output
+      .flatMap((spy) => spy.mock.calls)
+      .map(([message]) => String(message))
+      .filter((message) => /\[(WARN|ERROR)\] \[shipyard\]/.test(message))
+    return { processor, shipyardWarnings }
+  }
+
+  test('a site without markdown.processor builds warning-free on unified', async () => {
+    const { processor, shipyardWarnings } = await resolveWithAstro()
+
+    expect(shipyardWarnings).toEqual([])
+    expect(processor?.name).toBe(unified().name)
+  })
+
+  test('an explicitly configured satteri processor survives', async () => {
+    const { processor, shipyardWarnings } = await resolveWithAstro(
+      satteri({ features: { directive: true } }),
     )
+
+    expect(processor?.name).toBe(satteri().name)
+    expect(shipyardWarnings).toHaveLength(1)
+    expect(shipyardWarnings[0]).toContain('`satteri`')
   })
 })

package/src/markdownProcessor.ts

@@ -0,0 +1,65 @@
+import { isDeepStrictEqual } from 'node:util'
+import { isUnifiedProcessor, unified } from '@astrojs/markdown-remark'
+import { satteri } from '@astrojs/markdown-satteri'
+import type { AstroConfig, AstroIntegrationLogger } from 'astro'
+import { remarkAdmonitions } from './remark/remarkAdmonitions'
+import { remarkBlockDirective } from './remark/remarkBlockDirective'
+import { remarkNpm2Yarn } from './remark/remarkNpm2Yarn'
+
+type MarkdownProcessor = AstroConfig['markdown']['processor']
+
+const shipyardRemarkPlugins = [
+  remarkBlockDirective,
+  remarkAdmonitions,
+  remarkNpm2Yarn,
+]
+
+// Astro fills in a fresh `satteri()` when `markdown.processor` is unset, so
+// the resolved config cannot tell that default apart from an explicit bare
+// `satteri()`. Both render identically, so both count as "not chosen".
+const isAstroDefault = (processor: MarkdownProcessor) => {
+  const defaultProcessor = satteri()
+  return (
+    processor.name === defaultProcessor.name &&
+    isDeepStrictEqual(processor.options, defaultProcessor.options)
+  )
+}
+
+/**
+ * shipyard's admonitions, npm2yarn tabs and block directives are remark
+ * plugins, and only the `unified()` processor runs those.
+ *
+ * - Astro's default processor is replaced with `unified()` carrying the
+ *   shipyard plugins.
+ * - A `unified()` processor the user configured keeps all its options; the
+ *   shipyard plugins are appended to its own.
+ * - Any other processor the user configured is left untouched, with a warning
+ *   that the shipyard Markdown features will not render.
+ *
+ * Returns the processor to set, or `undefined` to leave the config alone.
+ */
+export const shipyardMarkdownProcessor = (
+  current: MarkdownProcessor,
+  logger: AstroIntegrationLogger,
+): MarkdownProcessor | undefined => {
+  if (isUnifiedProcessor(current)) {
+    return unified({
+      ...current.options,
+      remarkPlugins: [
+        ...current.options.remarkPlugins,
+        ...shipyardRemarkPlugins,
+      ],
+    })
+  }
+
+  if (isAstroDefault(current)) {
+    return unified({ remarkPlugins: shipyardRemarkPlugins })
+  }
+
+  logger.warn(
+    `\`markdown.processor\` is set to \`${current.name}\`, which does not run remark plugins, ` +
+      'so shipyard admonitions, npm2yarn tabs and block directives will not render. ' +
+      'Use `unified()` from `@astrojs/markdown-remark` to enable them.',
+  )
+  return undefined
+}

package/src/tools/linkChecker.test.ts

@@ -1,6 +1,7 @@
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
+import type { AstroIntegrationLogger } from 'astro'
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
 import type { LinkCheckResult } from './linkChecker'
 import { checkLinks, reportBrokenLinks } from './linkChecker'
@@ -168,15 +169,18 @@ describe('checkLinks', () => {
 })
 
 describe('reportBrokenLinks', () => {
-  const createMockLogger = () => ({
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-    debug: vi.fn(),
-    label: 'test',
-    options: {},
-    fork: vi.fn(),
-  })
+  const createMockLogger = () => {
+    const mock = {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+      label: 'test',
+      options: {},
+      fork: vi.fn(),
+    }
+    return mock as typeof mock & AstroIntegrationLogger
+  }
 
   test('logs success message when no broken links and action is not ignore', () => {
     const logger = createMockLogger()
@@ -186,7 +190,7 @@ describe('reportBrokenLinks', () => {
       brokenLinks: [],
     }
 
-    reportBrokenLinks(result, 'warn', logger as any)
+    reportBrokenLinks(result, 'warn', logger)
 
     expect(logger.info).toHaveBeenCalledWith(
       'Link check passed: 10 links verified',
@@ -204,7 +208,7 @@ describe('reportBrokenLinks', () => {
       ],
     }
 
-    reportBrokenLinks(result, 'ignore', logger as any)
+    reportBrokenLinks(result, 'ignore', logger)
 
     expect(logger.info).not.toHaveBeenCalled()
     expect(logger.warn).not.toHaveBeenCalled()
@@ -218,7 +222,7 @@ describe('reportBrokenLinks', () => {
       brokenLinks: [{ sourceFile: 'index.html', href: '/broken', line: 1 }],
     }
 
-    reportBrokenLinks(result, 'log', logger as any)
+    reportBrokenLinks(result, 'log', logger)
 
     expect(logger.info).toHaveBeenCalled()
     const message = logger.info.mock.calls[0]?.[0]
@@ -235,7 +239,7 @@ describe('reportBrokenLinks', () => {
       brokenLinks: [{ sourceFile: 'index.html', href: '/broken', line: 1 }],
     }
 
-    reportBrokenLinks(result, 'warn', logger as any)
+    reportBrokenLinks(result, 'warn', logger)
 
     expect(logger.warn).toHaveBeenCalled()
     const message = logger.warn.mock.calls[0]?.[0]
@@ -250,7 +254,7 @@ describe('reportBrokenLinks', () => {
       brokenLinks: [{ sourceFile: 'index.html', href: '/broken', line: 1 }],
     }
 
-    expect(() => reportBrokenLinks(result, 'throw', logger as any)).toThrow(
+    expect(() => reportBrokenLinks(result, 'throw', logger)).toThrow(
       'Broken links found',
     )
   })
@@ -267,7 +271,7 @@ describe('reportBrokenLinks', () => {
       ],
     }
 
-    reportBrokenLinks(result, 'warn', logger as any)
+    reportBrokenLinks(result, 'warn', logger)
 
     const message = logger.warn.mock.calls[0]?.[0]
     expect(message).toContain('Found 3 broken links')

package/src/virtual.d.ts

@@ -1,5 +1,6 @@
 declare module 'virtual:shipyard/config' {
   import type { Config } from './schemas/config'
+
   const config: Config
   export default config
 }