chore: migrate to debug

[luxass]

🔗 Linked issue

📚 Description

Summary by CodeRabbit

• New Features

  • Added optional, namespaced debug logging across API, filesystem, path utilities, and JSON parsing (enable via DEBUG).
  • Introduced a shared debugger utility for consistent instrumentation.
  • Enhanced tree flattening to a generic API with a standard node shape; empty directories are now included as paths.

• Documentation

  • Updated comments for path security checks and flattening behavior.

• Tests

  • Simplified flatten tests; marked legacy logging tests as TODO.

• Chores

  • Added debug and types to workspace; aligned build order with shared package; adjusted test log filtering configuration.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 76f12e9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Caution

Review failed

The pull request is closed.

Walkthrough

Introduces a shared debug utility and integrates optional debug logging across API handlers, fs-bridge, path-utils, and shared JSON utilities. Updates shared package exports and flattener typings to a generic TreeNode model. Adds workspace dependencies and build ordering for @ucdjs/shared, adjusts vitest console log filtering, and updates related tests.

Changes

Cohort / File(s)	Summary
Workspace deps and build wiring apps/api/package.json, packages/fetch/package.json, packages/fs-bridge/package.json, packages/path-utils/package.json, packages/shared/package.json, pnpm-workspace.yaml, apps/api/turbo.json	Adds @ucdjs/shared as workspace dependency across packages; introduces debug and @types/debug to catalogs; updates Turbo build dependencies to build @ucdjs/shared first.
API handlers and tests apps/api/src/lib/handlers.ts, apps/api/test/unit/handlers.test.ts	Replaces console logging with optional debugger (ucdjs:api); converts logging assertions to it.todo placeholders.
fs-bridge instrumentation packages/fs-bridge/src/assertions.ts, packages/fs-bridge/src/bridges/http.ts, packages/fs-bridge/src/bridges/node.ts, packages/fs-bridge/src/define.ts	Adds module-scoped debug loggers (ucdjs:fs-bridge:*) and emits logs on validation failures, IO errors, and unsupported operations; behavior unchanged.
path-utils instrumentation packages/path-utils/src/platform.ts, packages/path-utils/src/security.ts	Adds debug loggers (ucdjs:path-utils:*) for UNC detection, decoding/validation errors, and Windows-specific checks; no API changes.
Shared utilities: debugger, JSON, flatten, exports, tests packages/shared/src/debugger.ts, packages/shared/src/json.ts, packages/shared/src/flatten.ts, packages/shared/src/index.ts, packages/shared/test/flatten.test.ts	Adds createDebugger and re-exports; switches JSON parse errors to debug logs; refactors flattenFilePaths to generic over new TreeNode interface with adjusted traversal; updates tests accordingly.
Test runner config vitest.config.ts	Clears hiddenLogs filters (was four entries), leaving no onConsoleLog filtering; formatting-only map callback semicolon edits.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Client
  participant API as API Handler
  participant Debug as Debugger (ucdjs:api)

  Client->>API: Request
  alt Route found
    API-->>Client: Response
  else Not found
    API->>Debug: debug?.("Not Found", { path })
    API-->>Client: 404 JSON
  end
  opt Error
    API->>Debug: debug?.("Error processing request", { path, error })
    API-->>Client: 500 JSON
  end

Loading

sequenceDiagram
  autonumber
  participant Caller
  participant FS as FS Bridge
  participant Debug as Debugger (ucdjs:fs-bridge:*)

  Caller->>FS: exists/read/listdir(path)
  alt Happy path
    FS-->>Caller: Result
  else Validation/IO failure
    FS->>Debug: debug?.("Failure detail", { path/url, reason })
    FS-->>Caller: Error or false
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: add shared package #212 — Introduces the @ucdjs/shared package and exports (including debugger), directly related to new imports and usage here.
• refactor(ucd-store)!: rewrite entire ucd-store to be more composable #174 — Touches fs-bridge define flow; this PR adds debug instrumentation in the same area.
• refactor: migrate to new path utils package #241 — Modifies path-security logic in resolveSafePath; this PR adds debug logs around those checks.

Suggested labels

pkg: utils

Poem

A whisker-twitch, a gentle thrum—deb█ug springs to life, hum-hum.
I hop through paths and files so wide,
leaving carrot-crumbs of logs beside.
TreeNodes bloom where wild paths roam,
and errors whisper, “all is known.”
Thump! The build awaits—let’s hop it home. 🥕🐇

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

• Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
• Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2a2a902 and 76f12e9.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (21)

• apps/api/package.json (1 hunks)
• apps/api/src/lib/handlers.ts (2 hunks)
• apps/api/test/unit/handlers.test.ts (2 hunks)
• apps/api/turbo.json (1 hunks)
• packages/fetch/package.json (1 hunks)
• packages/fs-bridge/package.json (1 hunks)
• packages/fs-bridge/src/assertions.ts (2 hunks)
• packages/fs-bridge/src/bridges/http.ts (4 hunks)
• packages/fs-bridge/src/bridges/node.ts (1 hunks)
• packages/fs-bridge/src/define.ts (6 hunks)
• packages/path-utils/package.json (1 hunks)
• packages/path-utils/src/platform.ts (3 hunks)
• packages/path-utils/src/security.ts (8 hunks)
• packages/shared/package.json (1 hunks)
• packages/shared/src/debugger.ts (1 hunks)
• packages/shared/src/flatten.ts (2 hunks)
• packages/shared/src/index.ts (1 hunks)
• packages/shared/src/json.ts (2 hunks)
• packages/shared/test/flatten.test.ts (9 hunks)
• pnpm-workspace.yaml (2 hunks)
• vitest.config.ts (2 hunks)

✨ Finishing Touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch better-debug-log-control

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Preview Deployment for Web

The Web worker has been deployed successfully.

Preview URL: https://https://ucdjs-dev.luxass.workers.dev

This preview was built from commit 76f12e9

---

_{🤖 This comment will be updated automatically when you push new commits to this PR.}

[github-actions]

Preview Deployment for Api

The Api worker has been deployed successfully.

Preview URL: https://preview.api.ucdjs.dev

This preview was built from commit 76f12e9

---

_{🤖 This comment will be updated automatically when you push new commits to this PR.}

[codecov]

Codecov Report

❌ Patch coverage is 88.88889% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/fs-bridge/src/bridges/http.ts	75.00%	1 Missing ⚠️
packages/fs-bridge/src/define.ts	83.33%	1 Missing ⚠️
packages/shared/src/debugger.ts	75.00%	1 Missing ⚠️
packages/shared/src/flatten.ts	66.66%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull Request Overview

This PR migrates the codebase from using console.log and console.error for logging to using the debug library for more structured debugging. It introduces a standardized debugging system across packages and simplifies test configuration.

• Adds debug dependency and creates a centralized debugger utility in the shared package
• Replaces console logging with debug calls throughout the codebase
• Removes type dependencies on @ucdjs/fetch by creating local interfaces
• Simplifies vitest configuration by clearing hidden logs array

Reviewed Changes

Copilot reviewed 21 out of 22 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pnpm-workspace.yaml	Adds debug and @types/debug to catalog dependencies
packages/shared/src/debugger.ts	New utility for creating namespaced debug instances
packages/shared/src/json.ts	Replaces console.error with debug logging
packages/shared/src/flatten.ts	Removes @ucdjs/fetch dependency, adds local TreeNode interface
packages/path-utils/src/security.ts	Migrates console.error calls to debug logging
packages/fs-bridge/src/define.ts	Adds debug logging for bridge operations and errors
apps/api/src/lib/handlers.ts	Replaces console.error with structured debug logging
vitest.config.ts	Simplifies configuration by emptying hiddenLogs array

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (1)

apps/api/test/unit/handlers.test.ts:69

• This test is marked as todo and expects console.error calls that no longer exist after the migration to debug logging. The test should be updated to reflect the new debug-based logging or removed if not needed.

  it.todo("should log not found to console", async () => {
    const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
    await notFoundApp.request("/non-existing-route");
    expect(consoleErrorSpy).toHaveBeenCalledWith("[api]: Not Found:", "/non-existing-route");
    consoleErrorSpy.mockRestore();
  });

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}