When adding or changing API-like functions (parsers, clients, helpers), treat them as having a stable contract: define the accepted inputs and exact output shape, cover tricky edge cases with regression tests, and remove/deprecate superseded code paths so the API surface stays unambiguous.

How to apply:

• Specify the contract: what the function accepts (e.g., URL vs path formats; SSR/browser contexts) and the exact return fields.
• Add regression tests for known gaps: include edge-case inputs (e.g., relative paths, UNC paths) and verify the output shape.
• If an implementation/API was replaced, delete or clearly deprecate the old one—avoid leaving “dead code” that suggests multiple behaviors.

Example (contract + regression):

// Contract: treat GitHub URLs as { url } and local/UNC paths as { path }
function getCodebaseInput(input: string): { url?: string; path?: string } {
  // ...implementation
  return {};
}

// Regression cases for gaps
test('treats relative paths as paths', () => {
  expect(getCodebaseInput('../repo')).toEqual({ path: '../repo' });
});

test('treats UNC paths as paths', () => {
  expect(getCodebaseInput('\\server\\share\\repo')).toEqual({
    path: '\\server\\share\\repo',
  });
});

Checklist:

• Do we have tests that pin the contract for edge cases?
• Is the old implementation removed/deprecated after replacement?
• Do return types/fields remain consistent across contexts (SSR vs browser, URL vs path)?