docs: remove stale stub/TODO comments on implemented modules (#29)

[amondnet]

Summary

A stub audit found several modules carry "Minimal stub" / TODO(integration) / "throwing stub" comments that are stale — the code is fully implemented, so the comments mislead readers. This is a docs-only cleanup with zero behavior change (comments only; no logic touched).

Resolves #29.

Changes

• src/types.ts — drop // Minimal stub — full implementation lands in Unit 1. The file fully implements Chunk, SearchResult, and the chunkToDict / chunkFromDict / searchResultToDict round-trip helpers. Kept the // Port of src/semble/types.py reference.
• src/utils.ts — drop // Minimal stub — full implementation lands in Unit 3. isGitUrl, resolveChunk, formatResults, etc. are all implemented. Kept the port reference.
• src/cli.ts — drop // TODO(integration): replace stub when sibling modules land. All sibling imports (cache, index, mcp, stats, types, utils, version) are real and wired.
• src/indexing/index.ts — rewrite the stale "Wiring status" header block. Verified that fromGit (shallow clone → fromPath → re-root at URL) and loadFromDisk (reads manifest/chunks/bm25/vectors/args, validates schema version, reconstructs the index) are fully implemented. The new block accurately summarizes Construction (fromPath / fromGit / loadFromDisk) and Operations (search / findRelated / save), dropping the obsolete T00x task references and the "stub" / "throwing stub" language.

Out of scope

Genuine functional stubs are tracked separately (#26 dense embeddings, #27 ranking wiring, #28 ALL_LANGUAGES) and were not touched.

Verification

• bun run typecheck — clean
• bun run lint — clean
• bun test — 408 pass / 0 fail

(No CLI smoke — docs-only.)

---

Summary by cubic

Remove stale stub/TODO comments from implemented modules and update the src/indexing/index.ts header to accurately describe Construction (fromPath/fromGit/loadFromDisk) and Operations (search/findRelated/save). Docs-only cleanup with no behavior change; resolves #29.

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

Summary by CodeRabbit

• New Features

  • Established comprehensive type definitions for chunks, search results, and index statistics with serialization utilities.
  • Added utility functions for Git URL detection and chunk resolution.

• Documentation

  • Updated indexing module documentation with detailed construction and operations descriptions.

• Chores

  • Removed obsolete TODO comment.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: acee83fb-d1c2-48c8-aff7-0cfc906bedb7

📥 Commits

Reviewing files that changed from the base of the PR and between f03a732 and 33eca44.

📒 Files selected for processing (4)

• src/cli.ts
• src/indexing/index.ts
• src/types.ts
• src/utils.ts

💤 Files with no reviewable changes (3)

• src/utils.ts
• src/cli.ts
• src/types.ts

---

📝 Walkthrough

Walkthrough

Removes stale "Minimal stub" placeholder comments from src/types.ts and src/utils.ts, deletes a TODO(integration) comment from src/cli.ts, and rewrites the CspIndex header doc in src/indexing/index.ts to replace an outdated "Wiring status" block with an accurate "Construction / Operations" description. No executable code or public APIs are changed.

Changes

Stale comment cleanup

Layer / File(s)	Summary
Remove stub placeholders from types.ts and utils.ts src/types.ts, src/utils.ts	Removes the // Minimal stub — full implementation lands in Unit N. one-liner from the top of both files; all implementation below (enums, interfaces, serialization helpers, isGitUrl, resolveChunk, formatResults) was already present and is unchanged.
Remove TODO comment in CLI and update CspIndex header doc src/cli.ts, src/indexing/index.ts	Deletes the // TODO(integration): replace stub when sibling modules land line from src/cli.ts and rewrites the CspIndex comment block in src/indexing/index.ts from a "Wiring status" bullet list (which falsely marked fromGit and loadFromDisk as stubs) to a "Construction / Operations" narrative reflecting their implemented state.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐇 Hop hop, the stubs are gone today,
No more "TODO" to lead astray,
The code was real all along, you see,
Just dusty comments fooling me.
Clean comments now, the warren's free! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: removing stale stub/TODO comments from implemented modules, which matches the PR's documentation-only objective.
Linked Issues check	✅ Passed	All four stale comment removals requested in issue #29 are addressed: src/types.ts stub removed, src/utils.ts stub removed, src/cli.ts TODO removed, src/indexing/index.ts header rewritten. Code changes match documented implementation status.
Out of Scope Changes check	✅ Passed	All changes are documentation-only comment removals and header rewrites directly addressing issue #29's requirements. No out-of-scope behavioral, logic, or API changes were introduced.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/remove-stale-stub-comments-29

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed. For unrecoverable errors, disable the tool in CodeRabbit configuration.

---

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

[gemini-code-assist]

Code Review

이번 풀 리퀘스트는 src/cli.ts, src/types.ts, src/utils.ts 파일에서 더 이상 필요하지 않은 스텁(stub) 관련 주석과 TODO 메시지를 제거하고, src/indexing/index.ts 파일의 CspIndex 클래스 주석을 최신 구현 상태에 맞게 업데이트하는 작업을 수행합니다. 검토할 리뷰어의 피드백이 없으며, 변경 사항이 단순 주석 정리이므로 추가로 제공할 피드백은 없습니다.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 0 complexity · 0 duplication

Metric	Results
Complexity	0
Duplication	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

No issues found across 4 files

Architecture diagram

sequenceDiagram
    participant CLI
    participant MCP as MCP Server
    participant CspIndex as CspIndex
    participant Storage as File System / Git

    Note over CLI,Storage: Construction Phase

    CLI->>CspIndex: fromPath(path)
    CspIndex->>Storage: scan & read files
    Storage-->>CspIndex: file contents
    CspIndex->>CspIndex: build index (chunks, bm25, vectors)
    CspIndex-->>CLI: CspIndex instance

    CLI->>CspIndex: fromGit(url)
    CspIndex->>Storage: git shallow clone
    Storage-->>CspIndex: temp directory
    CspIndex->>CspIndex: delegate to fromPath
    CspIndex-->>CLI: CspIndex instance

    CLI->>CspIndex: loadFromDisk(path)
    CspIndex->>Storage: read manifest, chunks, bm25, vectors
    Storage-->>CspIndex: stored artifacts
    CspIndex->>CspIndex: reconstruct index
    CspIndex-->>CLI: instance

    Note over CLI,Storage: Operations Phase

    MCP->>CspIndex: search(query)
    CspIndex->>CspIndex: delegate to search logic
    CspIndex-->>MCP: search results

    MCP->>CspIndex: findRelated(chunk)
    CspIndex->>CspIndex: related chunk lookup
    CspIndex-->>MCP: related chunks

    CLI->>CspIndex: save(path)
    CspIndex->>Storage: persist artifacts
    Storage-->>CspIndex: success

Loading

_{Re-trigger cubic}