refactor: Rename lock file to docs-lock.json

[fbosch]

Summary

Rename lock file from docs.lock to docs-lock.json for consistency.

Changes

• Rename lock file constant from docs.lock to docs-lock.json
• Export DEFAULT_LOCK_FILENAME from main API module
• Replace execFileAsync with execa for better subprocess handling
• Add execa dependency with supporting packages
• Update all references to lock filename across codebase

Breaking Changes

Lock file naming changes; existing docs.lock files require migration.

[coderabbitai]

📝 Walkthrough

Walkthrough

Renamed the default lock filename from docs.lock to docs-lock.json, introduced and exported DEFAULT_LOCK_FILENAME from src/lock.ts (re-exported via the public API), updated code, docs, tests, and fixtures to use it, and propagated Path/PATHEXT into git child process env in src/git/fetch-source.ts.

Changes

Cohort / File(s)	Summary
Lock constant & API src/lock.ts, src/paths.ts, src/api.ts	Centralized DEFAULT_LOCK_FILENAME in src/lock.ts and changed its value to "docs-lock.json". Removed the old export from src/paths.ts and re-exported the constant via src/api.ts.
Runtime usage src/status.ts, scripts/benchmarks/run.mjs	Replaced hard-coded "docs.lock" with DEFAULT_LOCK_FILENAME imports for UI labels and benchmark temporary lock filenames.
Git env propagation src/git/fetch-source.ts	Switched to execa for git invocations and ensured PATH/Path and PATHEXT from process.env are included in the child process env.
Tests tests/.../*.test.js tests/edge-cases.test.js, tests/integration-real-repos.test.js, tests/lock.test.js, tests/sync-materialize.test.js, tests/sync-offline-fail.test.js, tests/sync-output.test.js, tests/sync-tool-version.test.js	Updated tests to import DEFAULT_LOCK_FILENAME (from the public API/dist) and replaced hard-coded lock filenames with uses of the constant; adjusted fixture paths and test setups accordingly.
Fixtures tests/fixtures/docs-lock.json, tests/fixtures/empty.docs-lock.json	Added new lock-format fixtures named for docs-lock.json containing example lock JSON data.
Docs & config .gitignore, AGENTS.md, README.md	Replaced references to docs.lock with docs-lock.json in docs, examples, and .gitignore.
Dependencies package.json	Added execa dependency for child-process invocations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Fix zero value handling in CLI output and explicit file protocol configuration #13 — Alters src/git/fetch-source.ts (similar changes to how git is invoked and environment is handled), likely related to the execa/env adjustments.

🐰 I nudged a filename, tiny and neat,
From dot-lock to dash-json — isn't that sweet?
One constant now leads each file in sight,
Tests, docs, and fixtures updated just right.
I hopped through envs so git finds its way.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title accurately reflects the primary change: renaming the lock file from docs.lock to docs-lock.json across the codebase.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch refactor/rename-lock-file

---

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.}

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/fbosch/docs-cache@16

commit: 5832a1a

[Copilot]

Pull request overview

This PR renames the lock file from docs.lock to docs-lock.json to follow a more conventional naming pattern with a clear file extension.

Changes:

• Updated DEFAULT_LOCK_FILENAME constant from "docs.lock" to "docs-lock.json" in src/lock.ts
• Moved constant export from src/paths.ts to src/lock.ts and re-exported via src/api.ts
• Updated all test files to import and use DEFAULT_LOCK_FILENAME instead of hardcoded strings
• Renamed fixture file tests/fixtures/empty.docs.lock to tests/fixtures/empty.docs-lock.json
• Updated documentation in README.md and AGENTS.md to reference new filename
• Updated .gitignore to ignore docs-lock.json instead of docs.lock

Reviewed changes

Copilot reviewed 15 out of 18 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/lock.ts	Changed DEFAULT_LOCK_FILENAME constant value from "docs.lock" to "docs-lock.json"
src/api.ts	Added export of DEFAULT_LOCK_FILENAME from lock module
src/paths.ts	Removed DEFAULT_LOCK_FILENAME constant (moved to lock.ts)
src/status.ts	Added import and usage of DEFAULT_LOCK_FILENAME for status display
tests/sync-tool-version.test.js	Updated to import and use DEFAULT_LOCK_FILENAME constant
tests/sync-output.test.js	Updated to import and use DEFAULT_LOCK_FILENAME constant
tests/sync-offline-fail.test.js	Updated to import and use DEFAULT_LOCK_FILENAME constant
tests/sync-materialize.test.js	Updated to import and use DEFAULT_LOCK_FILENAME constant
tests/lock.test.js	Updated to dynamically construct fixture path using DEFAULT_LOCK_FILENAME
tests/integration-real-repos.test.js	Updated to import and use DEFAULT_LOCK_FILENAME constant
tests/edge-cases.test.js	Updated to import and use DEFAULT_LOCK_FILENAME constant
tests/fixtures/empty.docs.lock	Deleted old fixture file
tests/fixtures/empty.docs-lock.json	Created new empty fixture file with renamed filename
tests/fixtures/docs.lock	Deleted fixture file containing vitest source data
README.md	Updated documentation to reference docs-lock.json
AGENTS.md	Updated documentation to reference docs-lock.json
.gitignore	Updated to ignore docs-lock.json instead of docs.lock
scripts/benchmarks/run.mjs	Updated to import and use DEFAULT_LOCK_FILENAME constant

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 3

🤖 Fix all issues with AI agents

In @.gitignore:
- Around line 9-10: Restore and retain the legacy docs.lock ignore entry
alongside the existing docs-lock.json entry in .gitignore so both patterns are
ignored during the deprecation window; specifically add or keep "docs.lock" in
the ignore list (in addition to "docs-lock.json") to prevent stale docs.lock
files from appearing as untracked.

In `@src/lock.ts`:
- Line 22: The DEFAULT_LOCK_FILENAME export was changed to "docs-lock.json" but
readLock still fails when older "docs.lock" files exist; update the readLock
function to check for the legacy filename "docs.lock" if DEFAULT_LOCK_FILENAME
is missing, prefer the new file when present, and if the legacy file is found
either migrate/rename it to DEFAULT_LOCK_FILENAME or read from it and log a
notice about the fallback; reference DEFAULT_LOCK_FILENAME and readLock so you
add the fallback existence check, read logic, and optional rename/notification
flow there.

In `@tests/lock.test.js`:
- Around line 24-27: The test fails because the fixture referenced by
module.DEFAULT_LOCK_FILENAME (expected filename docs-lock.json) is missing the
required sources.vitest entry; either rename tests/fixtures/empty.docs-lock.json
to docs-lock.json and add a sources.vitest.rulesSha256: "efgh" entry, or create
a new docs-lock.json fixture containing version, generatedAt, toolVersion and a
sources object with vitest.rulesSha256 set to "efgh" so the lock validation in
the test (fixturePath / module.DEFAULT_LOCK_FILENAME) finds the expected data.