chore: remove temp placeholder absolute paths

Author: 福晋

src/context.ts

@@ -220,9 +220,10 @@ export class Context {
       })
     );
 
-    // Internal type that extends Document with load-phase metadata
-    // not stored in the Document interface itself.
+    // Internal type that extends Document with load-phase metadata.
+    // id is required here — Context.load() always assigns it via pathToId.
     interface LoadedDoc extends Document {
+      id: string; // override optional Document.id → required
       contentHash?: string;
       sourceFilePath?: string;
     }

src/loaders/chunker.ts

@@ -44,9 +44,15 @@ export interface ChunkingOptions {
   strategy?: 'markdown' | 'fixed' | 'auto';
 }
 
+/** A document with a guaranteed ID — used by chunkers.
+ * Context.load() always assigns id via pathToId before chunking. */
+export interface ChunkableDocument extends Document {
+  id: string;
+}
+
 /** Chunker interface — custom chunkers can implement this. */
 export interface Chunker {
-  chunk(doc: Document): Chunk[];
+  chunk(doc: ChunkableDocument): Chunk[];
 }
 
 // ---------------------------------------------------------------------------
@@ -77,7 +83,7 @@ export class MarkdownChunker implements Chunker {
     this.chunkOverlap = opts.chunkOverlap;
   }
 
-  chunk(doc: Document): Chunk[] {
+  chunk(doc: ChunkableDocument): Chunk[] {
     return chunkMarkdown(doc, this.maxChunkSize, this.chunkOverlap);
   }
 }
@@ -87,7 +93,7 @@ export class MarkdownChunker implements Chunker {
  * sections that exceed maxChunkSize with a fixed-size sliding window.
  */
 function chunkMarkdown(
-  doc: Document,
+  doc: ChunkableDocument,
   maxChunkSize: number,
   overlap: number,
 ): Chunk[] {
@@ -205,7 +211,7 @@ export class FixedSizeChunker implements Chunker {
     this.chunkOverlap = opts.chunkOverlap;
   }
 
-  chunk(doc: Document): Chunk[] {
+  chunk(doc: ChunkableDocument): Chunk[] {
     const parts = fixedSizeSplit(doc.content, this.maxChunkSize, this.chunkOverlap);
     return parts.map((content, i) => ({
       content,
@@ -505,7 +511,7 @@ class AutoChunker implements Chunker {
     this.fixed = new FixedSizeChunker(options);
   }
 
-  chunk(doc: Document): Chunk[] {
+  chunk(doc: ChunkableDocument): Chunk[] {
     // If the document content contains markdown headings (## or ###), use
     // heading-aware chunking; otherwise fall back to fixed-size splits.
     if (/^#{1,3}\s+\S/m.test(doc.content)) {

src/loaders/json.ts

@@ -11,10 +11,7 @@ export class JsonLoader implements Loader {
     const content = await fs.readFile(filePath, 'utf-8');
     const data = JSON.parse(content);
 
-    // ID is a temporary placeholder — Context.load() derives the canonical
-    // hash-based ID from the path relative to basePath (cross-machine consistency).
     return {
-      id: filePath,
       content: typeof data === 'string' ? data : JSON.stringify(data, null, 2),
     };
   }

src/loaders/markdown.ts

@@ -12,10 +12,7 @@ export class MarkdownLoader implements Loader {
     const content = await fs.readFile(filePath, 'utf-8');
     const { data: meta, content: body } = matter(content);
 
-    // ID is a temporary placeholder — Context.load() derives the canonical
-    // hash-based ID from the path relative to basePath (cross-machine consistency).
     return {
-      id: filePath,
       content: body.trim(),
       meta,
     };

src/loaders/text.ts

@@ -10,10 +10,7 @@ export class TextLoader implements Loader {
   async load(filePath: string): Promise<Document> {
     const content = await fs.readFile(filePath, 'utf-8');
 
-    // ID is a temporary placeholder — Context.load() derives the canonical
-    // hash-based ID from the path relative to basePath (cross-machine consistency).
     return {
-      id: filePath,
       content: content.trim(),
     };
   }

src/types.ts

@@ -2,8 +2,10 @@
  * Document structure
  */
 export interface Document {
-  /** Document unique identifier (default: file path) */
-  id: string;
+  /** Document unique identifier — assigned by Context.load() (hash-based).
+   * Not set by Loaders; Context.load() derives it from the file path
+   * relative to basePath for cross-machine consistency. */
+  id?: string;
   /** Document content */
   content: string;
   /** Markdown front-matter metadata */

test/loaders.test.ts

@@ -13,9 +13,9 @@ describe('Loaders', () => {
       const filePath = path.join(FIXTURES_DIR, 'getting-started.md');
       const doc = await loader.load(filePath);
 
-      // Loader returns the file path as a temporary ID — the canonical
-      // hash-based ID is assigned by Context.load() for cross-machine consistency.
-      expect(doc.id).toBe(filePath);
+      // Loader does not assign id — the canonical hash-based ID is
+      // assigned by Context.load() for cross-machine consistency.
+      expect(doc.id).toBeUndefined();
       expect(doc.content).toContain('Getting Started');
       expect(doc.content).toContain('npm install');
       expect(doc.meta).toEqual({
@@ -38,7 +38,7 @@ describe('Loaders', () => {
       const filePath = path.join(FIXTURES_DIR, 'api.json');
       const doc = await loader.load(filePath);
 
-      expect(doc.id).toBe(filePath);
+      expect(doc.id).toBeUndefined();
       expect(doc.content).toContain('API Reference');
       expect(doc.content).toContain('/users');
     });
@@ -56,7 +56,7 @@ describe('Loaders', () => {
       const filePath = path.join(FIXTURES_DIR, 'notes.txt');
       const doc = await loader.load(filePath);
 
-      expect(doc.id).toBe(filePath);
+      expect(doc.id).toBeUndefined();
       expect(doc.content).toContain('notes');
     });