[Refactor]: Rename capture.ts and format.ts to entity-name concepts #76

Current State

Two files in packages/errors/src/error/ are named after what they do for the caller rather than what they are:

• capture.ts — the file exposes captureStack(message: string): string. The file name is a verb (capture); it should be a noun (the concept: stack trace utilities).
• format.ts — the file exposes formatTemplate and hasTemplatePlaceholders. The file name is a verb (format); it should be a noun (the concept: message template formatting).

Rule 0013 (Entity-First Naming) refuses bare job titles and verb-noun patterns at the type and module level:

"A bare job title is a confession that the author could not name the thing they were building."

The rule's exception list is for cases like UserManagerTest (the test mirrors the type under test), and for variables that hold an instance briefly. File names are not on the exception list. Rule 0002 (File Separation) reinforces: a file's name should describe its purpose and age well.

Located in:

• packages/errors/src/error/capture.ts
• packages/errors/src/error/format.ts

The rest of the package follows the entity-name pattern: error/, causes/, is/, raise/ are all concept names (what the concern is), not action names.

Proposed State

After refactoring, the files are renamed to concept names:

• capture.ts → stack-trace.ts (the concept: utilities for capturing and cleaning stack traces)
• format.ts → message-template.ts (the concept: utilities for formatting message templates)

The directory structure is unchanged. All import paths in error.ts and elsewhere are updated to match.

Expected improvements:

• Rule 0013 compliance: file names are entity names, not verbs.
• The reader can grep for "stack trace" or "message template" and find the right file by concept, not by guessing the action.
• Consistency with the rest of the package (error/, causes/, is/, raise/).
• Rule 0002 (File Separation) is reinforced: each file has a concept it owns.

Motivation

This refactoring is needed because:

• The verb-noun names confuse the rule 0002 / 0013 mental model. A reader who lands on capture.ts wonders "capture what?", and the answer is in the file body, not the name.
• Renaming aligns the package with the rest of the structure: every other concern folder is named after what it is.
• The cost of renaming is mechanical (git mv + import updates) and reviewable in one commit.

Triggers for this work:

• Technical debt accumulation
• Maintainability concerns

Risks

Potential risks:

• Risk 1: Renaming breaks the package's import graph. — Mitigation: the renames are local to src/error/; imports are updated in the same commit; the build pipeline catches any missed reference.
• Risk 2: External consumers do not import these files directly. — Mitigation: the files are internal (captureStack, formatTemplate, hasTemplatePlaceholders are not exported from the public index.ts). The risk is zero for external consumers.

Migration Plan

Migration approach:

1. git mv packages/errors/src/error/capture.ts packages/errors/src/error/stack-trace.ts
2. git mv packages/errors/src/error/format.ts packages/errors/src/error/message-template.ts
3. Update imports in error.ts (the only file that imports from them).
4. Run the test suite and type check.

Rollback plan: revert the PR.

Backward Compatibility

• This refactoring maintains full backward compatibility

Scope

Files/Folders affected:

• packages/errors/src/error/capture.ts → renamed
• packages/errors/src/error/format.ts → renamed
• packages/errors/src/error/error.ts (imports updated)
• packages/errors/tsconfig.build.json (no change expected)

Component(s) Affected

• Multiple Components

Note: the component_affected dropdown is calibrated for a web template project. The actual affected component is packages/errors.

Priority

• p0: Critical - Blocking major work or causing bugs
• p1: High - Important, should do soon
• p2: Medium - Normal priority
• p3: Low - Nice to have

Estimated Effort

• effort: xs - Few minutes

Test Coverage Requirements

• Existing tests cover this code area (will update)

Testing Approach

Verification steps:

1. pnpm --filter @deessejs/errors test:run
2. pnpm --filter @deessejs/errors type-check
3. pnpm --filter @deessejs/errors build — confirm the dist output matches the public API.

Related Issues / Pull Requests

• Related audit: P0 chore: merge dev to main - core foundation complete #6 in the internal audit of packages/errors/src/ against rules 0001-0016, August 2026.
• Related rule: docs/engineering/architecture/rules/0013-entity-first-naming.md.
• Related rule: docs/engineering/architecture/rules/0002-file-separation.md.

Relevant Documentation

• Architecture doc: docs/engineering/architecture/rules/0013-entity-first-naming.md
• Architecture doc: docs/engineering/architecture/rules/0002-file-separation.md

Pre-Submission Checklist

• I have searched existing issues for related refactoring requests
• Risks and migration plan are documented
• Test coverage approach is defined
• I understand this issue will be labeled according to the project taxonomy
• This is NOT a security vulnerability (see security note above)