feat(utils): port isGitUrl/resolveChunk/formatResults from semble

[amondnet]

Port `src/semble/utils.py` to TypeScript as part of the parallel @pleaseai/csp port effort (Unit 3).

What changed

• `src/utils.ts` — exports:
  • `isGitUrl(path)`: detects remote git URLs by scheme prefix (`https://`, `http://`, `ssh://`, `git://`, `git+ssh://`, `file://`) or scp-style `user@host:repo` (regex `/^[\w.-]+@[\w.-]+:(?!/)/` — excludes `user@host:/abs/path`).
  • `resolveChunk(chunks, filePath, line)`: returns the chunk containing `line`. Strict inner match (`line < endLine`) wins immediately; boundary match (`line === endLine`) is kept only as a fallback for end-of-file chunks. Mirrors Python logic exactly.
  • `formatResults(query, results)`: wraps `SearchResult.toDict()` outputs as `{ query, results }`.
• `src/utils.test.ts` — 25 unit tests covering scheme detection, scp-style URLs, the `user@host:/path` exclusion, inner/boundary chunk resolution, multi-fallback ordering, cross-file filtering, and `formatResults` shape/ordering.

Stopgap types

`src/types.ts` doesn't exist yet (Unit 1's territory). Per the task brief, structural `Chunk` / `SearchResult` types are defined inline using camelCase fields (`filePath`, `startLine`, `endLine`) per the @pleaseai/csp public-API convention. These should be replaced with re-exports from `./types.ts` once Unit 1 merges.

Verification

```
bun test src/utils.test.ts
25 pass
0 fail
25 expect() calls
```

Source

`src/semble/utils.py`

---

Summary by cubic

Ports isGitUrl, resolveChunk, and formatResults from Python to TypeScript with full test coverage. This delivers Unit 3 utils for the @pleaseai/csp port and keeps behavior 1:1 with the original.

• New Features
  • src/utils.ts exports:
    • isGitUrl(path): detects git URLs by scheme or scp-style user@host:repo (excludes user@host:/abs/path).
    • resolveChunk(chunks, filePath, line): strict inner match wins; endLine boundary is a fallback.
    • formatResults(query, results): returns { query, results } via toDict().
  • Stopgap Chunk/SearchResult interfaces inline; replace with ./types.ts when available.
  • src/utils.test.ts: 25 tests for URL detection, chunk resolution, and result formatting.

^{Written for commit fb5cb4e. Summary will update on new commits.}

[gemini-code-assist]

Code Review

This pull request ports utility functions and their corresponding tests from Python to TypeScript, introducing helper functions for identifying Git URLs, resolving code chunks by line number, and formatting search results. The review feedback suggests improving cross-platform compatibility in resolveChunk by normalizing path separators to handle Windows backslashes and adding a unit test to verify this behavior.

[cubic-dev-ai]

No issues found across 2 files

Architecture diagram

sequenceDiagram
    participant Client as Caller (e.g. Search API)
    participant Utils as utils.ts
    participant Types as types.ts (future)
    participant Python as Original semble Python

    Note over Client,Python: Port of `src/semble/utils.py` to TypeScript

    Client->>Utils: isGitUrl(path)
    alt Scheme match (https://, http://, ssh://, git://, git+ssh://, file://)
        Utils->>Utils: Check path.startsWith(scheme)
        Utils-->>Client: true
    else SCP-style match (user@host:repo)
        Utils->>Utils: Test /^[\w.-]+@[\w.-]+:(?!\/)/
        Utils-->>Client: true / false
    else No match
        Utils-->>Client: false
    end

    Client->>Utils: resolveChunk(chunks, filePath, line)
    Utils->>Utils: Iterate chunks matching filePath
    alt line < endLine (strict inner match)
        Utils->>Utils: Return chunk immediately
    else line === endLine (boundary match)
        Utils->>Utils: Store as fallback (first only)
    end
    Note over Utils: After loop, return fallback or null

    Client->>Utils: formatResults(query, results)
    Utils->>Utils: Map results via toDict()
    Utils-->>Client: { query, results }

    Note over Types: Stopgap inline types until Unit 1 merges
    Note over Python: Behavior identical to Python original

Loading

_{Re-trigger cubic}

[amondnet]

Applied 0, deferred 2.

Both gemini-code-assist comments asked to add backslash→slash path normalization inside resolveChunk plus a matching test. Deferring both:

• Upstream semble.utils.resolve_chunk uses strict chunk.file_path == file_path equality — no normalization. Parity with semble is load-bearing for this port (per CLAUDE.md).
• resolveChunk is a pure key lookup over chunks produced by the indexer. Cross-platform path canonicalization is a file-walker / indexing concern (Unit 8), where both stored and queried paths can share one canonical form. Normalizing only at the lookup site would mask, not fix, inconsistent emission.

cubic-dev-ai found no issues.