fix(packages/core): use deep glob pattern for recursive workspace includes (#69)

* fix(packages/core): use deep glob pattern for recursive workspace includes

The default include pattern for workspace items was always `docs/*.md`
regardless of the `recursive` flag. This meant recursive mode with
no explicit `include` would only discover files at the top level of
`docs/`, never in subdirectories like `docs/guides/setup.md`.

Switch the default to `docs/**/*.md` when `recursive: true` so
fast-glob discovers nested files as expected.

Co-Authored-By: Claude <noreply@anthropic.com>

* chore(repo): add changeset and disable coderabbit walkthrough

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: apply CodeRabbit auto-fixes

Fixed 1 file(s) based on 1 unresolved review comment.

Co-authored-by: CodeRabbit <noreply@coderabbit.ai>

* chore(repo): gut coderabbit walkthrough content

Collapse walkthrough and disable all sub-features: changed files
summary, sequence diagrams, linked issues, related issues/PRs,
and review status messages.

Co-Authored-By: Claude <noreply@anthropic.com>

* chore(repo): disable all coderabbit walkthrough sub-features

Disable every feature that populates the walkthrough comment:
high_level_summary, review_status, review_details, changed_files_summary,
sequence_diagrams, estimate_code_review_effort, assess_linked_issues,
related_issues, related_prs. The walkthrough comment itself has no
master toggle in the v2 schema — this is as close to off as it gets.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(packages/core): prevent double-prefixing repo-relative include paths

When a workspace item provides an explicit repo-relative include like
`apps/api/docs/**/*.md`, `normalizeAndResolveInclude` was prepending
the basePath derived from `path`, producing a broken double path:
`apps/api/apps/api/docs/**/*.md`. The glob silently matched 0 files,
so only landing pages appeared in the output.

Skip the basePath prefix when the pattern already starts with it.

Co-Authored-By: Claude <noreply@anthropic.com>

* chore(repo): update changeset to cover both workspace fixes

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(packages/core): warn on double-prefixed include instead of auto-correcting

Replace the silent auto-fix with a warning that tells the user their
include pattern is already repo-relative and will be double-prefixed.
Include is documented as relative to the workspace path — the user
should fix their config.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(packages/core): move include prefix check to config validation

Remove the log.warn from the sync hot path and add a proper config
check that surfaces during `zpress check`. When a workspace include
pattern already starts with the basePath derived from path, warn that
the resolved glob will be double-prefixed and likely match zero files.

- Add ConfigWarning type and configWarning factory to @zpress/config
- Add checkWorkspaceIncludes to @zpress/core (exported)
- Wire warnings into runConfigCheck and presentResults in @zpress/cli

Co-Authored-By: Claude <noreply@anthropic.com>

* docs(packages/core): update JSDoc for conditional include default

Reflect that the default include pattern is now docs/**/*.md when
recursive is true, otherwise docs/*.md.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(packages/core): remove glob patterns from JSDoc to fix declaration emit

TypeScript's declaration emitter interprets the sequence star-slash
inside JSDoc backtick spans as end-of-comment, breaking the build.
Remove glob examples from exported function JSDoc blocks.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(packages/cli): add warnings field to check test fixtures

The ConfigCheckResult interface gained a warnings field but existing
test fixtures were not updated, causing presentResults to crash on
configResult.warnings.length.

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: CodeRabbit <noreply@coderabbit.ai>

Author: 4 people

.changeset/fix-recursive-workspace-glob.md

@@ -0,0 +1,10 @@
+---
+'@zpress/core': patch
+'@zpress/config': patch
+'@zpress/cli': patch
+---
+
+Fix workspace include resolution for `apps` and `packages` items:
+
+- Use deep glob pattern (`docs/**/*.md`) as default include when `recursive: true`. Previously the default was always `docs/*.md` regardless of the flag.
+- Add config check warning when an explicit include pattern already starts with the basePath derived from `path`, which causes double-prefixing and silently matches zero files. Surfaces during `zpress check` before the build step.

.coderabbit.yaml

@@ -6,17 +6,19 @@ early_access: true
 reviews:
   profile: assertive
   request_changes_workflow: true
-  high_level_summary: true
+  high_level_summary: false
   high_level_summary_in_walkthrough: false
-  review_status: true
+  review_status: false
+  review_details: false
   commit_status: true
   fail_commit_status: false
-  collapse_walkthrough: false
-  changed_files_summary: true
-  sequence_diagrams: true
-  assess_linked_issues: true
-  related_issues: true
-  related_prs: true
+  collapse_walkthrough: true
+  changed_files_summary: false
+  sequence_diagrams: false
+  estimate_code_review_effort: false
+  assess_linked_issues: false
+  related_issues: false
+  related_prs: false
   suggested_labels: false
   suggested_reviewers: false
   poem: false

packages/cli/src/lib/check.test.ts

@@ -18,6 +18,7 @@ const loadError = {
 const mockLogger = {
   success: vi.fn(),
   error: vi.fn(),
+  warn: vi.fn(),
   message: vi.fn(),
 }
 
@@ -48,7 +49,7 @@ describe('runConfigCheck()', () => {
 describe('presentResults()', () => {
   it('should return true when both config passed and build passed', () => {
     const result = presentResults({
-      configResult: { passed: true, errors: [] },
+      configResult: { passed: true, errors: [], warnings: [] },
       buildResult: { status: 'passed' },
       logger: mockLogger,
     })
@@ -57,7 +58,7 @@ describe('presentResults()', () => {
 
   it('should return false when config failed', () => {
     const result = presentResults({
-      configResult: { passed: false, errors: [loadError] },
+      configResult: { passed: false, errors: [loadError], warnings: [] },
       buildResult: { status: 'passed' },
       logger: mockLogger,
     })
@@ -66,7 +67,7 @@ describe('presentResults()', () => {
 
   it('should return false when build has deadlinks', () => {
     const result = presentResults({
-      configResult: { passed: true, errors: [] },
+      configResult: { passed: true, errors: [], warnings: [] },
       buildResult: {
         status: 'failed',
         deadlinks: [{ file: 'docs/page.md', links: ['/missing'] }],
@@ -78,7 +79,7 @@ describe('presentResults()', () => {
 
   it('should call logger.success when config is valid', () => {
     presentResults({
-      configResult: { passed: true, errors: [] },
+      configResult: { passed: true, errors: [], warnings: [] },
       buildResult: { status: 'passed' },
       logger: mockLogger,
     })
@@ -87,7 +88,7 @@ describe('presentResults()', () => {
 
   it('should call logger.error when config failed', () => {
     presentResults({
-      configResult: { passed: false, errors: [loadError] },
+      configResult: { passed: false, errors: [loadError], warnings: [] },
       buildResult: { status: 'skipped' },
       logger: mockLogger,
     })

packages/cli/src/lib/check.ts

@@ -10,8 +10,8 @@
 import path from 'node:path'
 
 import type { CliLogger } from '@kidd-cli/core/logger'
-import { configError } from '@zpress/core'
-import type { ConfigError, Paths, ZpressConfig } from '@zpress/core'
+import { configError, checkWorkspaceIncludes } from '@zpress/core'
+import type { ConfigError, ConfigWarning, Paths, ZpressConfig } from '@zpress/core'
 
 import { toError } from './error.ts'
 import { buildSiteForCheck } from './rspress.ts'
@@ -20,6 +20,7 @@ import { buildSiteForCheck } from './rspress.ts'
 const ANSI_PATTERN = /\u001B\[[0-9;]*m/g
 
 const RED = '\u001B[31m'
+const YELLOW = '\u001B[33m'
 const DIM = '\u001B[2m'
 const RESET = '\u001B[0m'
 
@@ -31,6 +32,7 @@ interface DeadlinkInfo {
 interface ConfigCheckResult {
   readonly passed: boolean
   readonly errors: readonly ConfigError[]
+  readonly warnings: readonly ConfigWarning[]
 }
 
 type BuildCheckResult =
@@ -75,12 +77,13 @@ interface RunConfigCheckParams {
 export function runConfigCheck(params: RunConfigCheckParams): ConfigCheckResult {
   const { config, loadError } = params
   if (loadError) {
-    return { passed: false, errors: [loadError] }
+    return { passed: false, errors: [loadError], warnings: [] }
   }
   if (!config) {
-    return { passed: false, errors: [configError('empty_sections', 'Config is missing')] }
+    return { passed: false, errors: [configError('empty_sections', 'Config is missing')], warnings: [] }
   }
-  return { passed: true, errors: [] }
+  const warnings = checkWorkspaceIncludes(config)
+  return { passed: true, errors: [], warnings }
 }
 
 /**
@@ -142,6 +145,15 @@ export function presentResults(params: PresentResultsParams): boolean {
     })
   }
 
+  if (configResult.warnings.length > 0) {
+    logger.warn(`${configResult.warnings.length} config warning(s):`)
+    // oxlint-disable-next-line no-unused-expressions -- side-effect logging over config warnings
+    configResult.warnings.map((w) => {
+      logger.message(`  ${YELLOW}⚠${RESET} ${w.message}`)
+      return null
+    })
+  }
+
   if (buildResult.status === 'passed') {
     logger.success('No broken links')
   } else if (buildResult.status === 'skipped') {

packages/config/schemas/schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://raw.githubusercontent.com/joggrdocs/zpress/v0.4.0/packages/config/schemas/schema.json",
+  "$id": "https://raw.githubusercontent.com/joggrdocs/zpress/v0.5.0/packages/config/schemas/schema.json",
   "title": "Zpress Configuration",
   "description": "Configuration file for zpress documentation framework",
   "$ref": "#/definitions/ZpressConfig",

packages/config/src/errors.ts

@@ -1,5 +1,5 @@
 /**
- * Error types for config loading and validation.
+ * Error and warning types for config loading and validation.
  */
 
 import type { ZodError } from 'zod/v3'
@@ -33,6 +33,17 @@ export interface ConfigError {
 
 export type ConfigResult<T> = Result<T, ConfigError>
 
+export type ConfigWarningType = 'duplicate_include_prefix'
+
+/**
+ * Non-fatal config issue that may cause unexpected behavior.
+ */
+export interface ConfigWarning {
+  readonly _tag: 'ConfigWarning'
+  readonly type: ConfigWarningType
+  readonly message: string
+}
+
 /**
  * Create a ConfigError with the given type and message.
  *
@@ -48,6 +59,21 @@ export function configError(type: ConfigErrorType, message: string): ConfigError
   }
 }
 
+/**
+ * Create a ConfigWarning with the given type and message.
+ *
+ * @param type - The warning type discriminant
+ * @param message - Human-readable warning message
+ * @returns A ConfigWarning object
+ */
+export function configWarning(type: ConfigWarningType, message: string): ConfigWarning {
+  return {
+    _tag: 'ConfigWarning',
+    type,
+    message,
+  }
+}
+
 /**
  * Convert a Zod validation error into a ConfigError.
  *

packages/config/src/index.ts

@@ -39,8 +39,14 @@ export { validateConfig } from './validator.ts'
 
 export { zpressConfigSchema, pathsSchema } from './schema.ts'
 
-export { configError, configErrorFromZod } from './errors.ts'
-export type { ConfigError, ConfigErrorType, ConfigResult } from './errors.ts'
+export { configError, configErrorFromZod, configWarning } from './errors.ts'
+export type {
+  ConfigError,
+  ConfigErrorType,
+  ConfigResult,
+  ConfigWarning,
+  ConfigWarningType,
+} from './errors.ts'
 
 export {
   THEME_NAMES,

packages/core/src/index.ts

@@ -40,6 +40,8 @@ export type {
 } from './sync/types.ts'
 export type { SyncError, SyncOutcome, ConfigError, ConfigResult } from './sync/errors.ts'
 export { syncError, configError } from './sync/errors.ts'
+export type { ConfigWarning, ConfigWarningType } from '@zpress/config'
+export { checkWorkspaceIncludes } from './sync/workspace.ts'
 
 export {
   generateAssets,

packages/core/src/sync/workspace.ts

@@ -1,6 +1,9 @@
+import { configWarning } from '@zpress/config'
+import type { ConfigWarning } from '@zpress/config'
 import { isNil, isString, isUndefined, kebabCase, omitBy } from 'es-toolkit'
 import { match, P } from 'ts-pattern'
 
+import { normalizeInclude } from '../glob.ts'
 import { resolveOptionalIcon, serializeIcon } from '../icon.ts'
 import type { Section, TitleConfig, ZpressConfig, Workspace } from '../types.ts'
 import { collectAllWorkspaceItems } from './collect-workspaces.ts'
@@ -240,6 +243,22 @@ export function synthesizeWorkspaceSections(config: ZpressConfig): Section[] {
   )
 }
 
+/**
+ * Check workspace items for include patterns that will be double-prefixed.
+ *
+ * When a workspace `include` pattern already starts with the basePath
+ * derived from `path`, the resolved glob becomes double-prefixed
+ * and will silently match zero files. This produces warnings so the
+ * user can fix their config before broken links appear in the build.
+ *
+ * @param config - Validated zpress config
+ * @returns Array of warnings for any workspace items with suspect includes
+ */
+export function checkWorkspaceIncludes(config: ZpressConfig): readonly ConfigWarning[] {
+  const allItems = collectAllWorkspaceItems(config)
+  return allItems.flatMap((item) => checkItemInclude(item))
+}
+
 /**
  * Convert display text to a URL-safe slug.
  * E.g. "Getting Started" → "getting-started", "updatePet" → "update-pet"
@@ -255,6 +274,32 @@ export function slugify(text: string): string {
 // Private
 // ---------------------------------------------------------------------------
 
+/**
+ * Check a single workspace item for include patterns that already start
+ * with the basePath derived from `path`.
+ *
+ * @private
+ * @param item - Workspace item to check
+ * @returns Array of warnings (empty if no issues)
+ */
+function checkItemInclude(item: Workspace): readonly ConfigWarning[] {
+  if (item.include === null || item.include === undefined) {
+    return []
+  }
+  const basePath = item.path.replace(/^\//, '')
+  const patterns = normalizeInclude(item.include)
+  return patterns
+    .filter((pattern) => pattern.startsWith(basePath))
+    .map((pattern) =>
+      configWarning(
+        'duplicate_include_prefix',
+        `Workspace "${String(item.title)}" include "${pattern}" already starts with "${basePath}" — ` +
+          `it will resolve to "${basePath}/${pattern}" which likely matches zero files. ` +
+          `Did you mean "${pattern.slice(basePath.length + 1)}"? (include is relative to path)`
+      )
+    )
+}
+
 /**
  * Recursively collect all links from a section tree.
  * Walks sections and their nested items to find every defined link.
@@ -381,9 +426,8 @@ function buildWorkspaceSection(
  *
  * Uses `path` as both the section URL and URL prefix for glob-discovered children.
  * The `include` field is resolved relative to the workspace item's base path
- * (derived from `path`). Defaults to `"docs/*.md"` when omitted.
- *
- * For example, `path: "/apps/api"` + `include: "docs/*.md"` resolves to `"apps/api/docs/*.md"`.
+ * (derived from `path`). When `recursive` is true the default include is a deep
+ * glob matching all nested markdown, otherwise a shallow single-level glob.
  *
  * @private
  * @param item - Workspace item to convert
@@ -408,7 +452,10 @@ function workspaceToSection(item: Workspace): Section {
  * @returns Complete section with all discovery fields resolved
  */
 function applyOptionalFields(base: Section, item: Workspace): Section {
-  const fromPattern = item.include ?? 'docs/*.md'
+  const defaultPattern = match(item.recursive)
+    .with(true, () => 'docs/**/*.md')
+    .otherwise(() => 'docs/*.md')
+  const fromPattern = item.include ?? defaultPattern
   const basePath = item.path.replace(/^\//, '')
   const resolvedInclude = normalizeAndResolveInclude(fromPattern, basePath)