@isaacriehm/cairn-core 0.1.0

package/dist/init/source-comments/walker.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Phase 7b — deterministic source-comment walker.
+ *
+ * Walks every source file in the repo (via `git ls-files` when available, else
+ * a manual recursive walk respecting a hardcoded ignore list) and extracts
+ * essay-style comment blocks per language. Detection is deterministic — no
+ * LLM. The output feeds the Haiku batch classifier (`classify.ts`).
+ *
+ * "Essay-style" heuristic per spec §15:
+ *   - block comment > 3 lines, OR
+ *   - block comment > 200 chars, OR
+ *   - JSDoc with > 30 words of prose (after stripping @tags + symbols).
+ *
+ * License headers are detected separately and exported with `kind: "license"`
+ * — the classifier passes them through; the strip-replace stage leaves them
+ * in source untouched.
+ */
+export type CommentLang = "js" | "py" | "rs" | "go" | "java" | "c" | "cs" | "rb" | "sh" | "php" | "lua" | "dart" | "kt" | "swift" | "scala" | "unknown";
+export type CommentKind = "block" | "jsdoc" | "line-cluster" | "license";
+export interface CommentBlock {
+    /** Stable per-walk id: `<rel-path>:<startLine>-<endLine>` */
+    id: string;
+    /** Repo-relative POSIX path. */
+    file: string;
+    lang: CommentLang;
+    kind: CommentKind;
+    /** 1-based, inclusive. */
+    startLine: number;
+    /** 1-based, inclusive. */
+    endLine: number;
+    /** Raw text including comment markers. */
+    raw: string;
+    /** Stripped prose — markers + leading `*` removed, used for word count. */
+    prose: string;
+    lineCount: number;
+    charCount: number;
+    wordCount: number;
+    /** Index where `raw` starts in the file (UTF-8 bytes ≈ chars for source). */
+    startOffset: number;
+    /** Index immediately after `raw`. */
+    endOffset: number;
+}
+export interface WalkOptions {
+    repoRoot: string;
+    /** Cap on files to read; default unlimited (full repo per spec). */
+    fileCap?: number;
+    /** When set, only walk these paths (repo-relative). Used by tests. */
+    onlyFiles?: string[];
+}
+export interface WalkResult {
+    files: string[];
+    blocks: CommentBlock[];
+    /** Per-language file count for telemetry. */
+    fileCountByLang: Record<string, number>;
+    /** Total raw chars scanned. */
+    bytesScanned: number;
+}
+export declare function walkSourceComments(opts: WalkOptions): WalkResult;
+export declare function detectLang(file: string): CommentLang;
+export declare const HEURISTIC: {
+    MIN_LINES: number;
+    MIN_CHARS: number;
+    MIN_JSDOC_WORDS: number;
+};
+export declare function _existsForTest(p: string): boolean;