@dennisrongo/dsh-todo 0.4.1 → 0.5.1

package/lib/scan.js

@@ -0,0 +1,276 @@
+// src/scan.ts
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+var DIGEST_BYTE_CAP = 24e3;
+var IGNORED_DIRS = /* @__PURE__ */ new Set([
+  ".git",
+  ".hg",
+  ".svn",
+  "node_modules",
+  "bower_components",
+  "jspm_packages",
+  "lib",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  ".next",
+  ".nuxt",
+  ".svelte-kit",
+  ".output",
+  ".parcel-cache",
+  ".turbo",
+  ".cache",
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".tox",
+  ".mypy_cache",
+  ".pytest_cache",
+  "target",
+  "vendor",
+  "vendored",
+  "third_party",
+  "thirdparty",
+  "generated",
+  "__generated__",
+  "Pods",
+  "Carthage",
+  "DerivedData"
+]);
+var SOURCE_EXT = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".go",
+  ".rs",
+  ".java",
+  ".rb",
+  ".php",
+  ".cs",
+  ".swift",
+  ".kt",
+  ".scala",
+  ".sh"
+]);
+var MAX_FILES_WALKED = 4e3;
+var MAX_TREE_ENTRIES = 300;
+var MAX_COMMENTS = 80;
+var MAX_UNTESTED = 40;
+var MAX_COMMENT_LINE = 160;
+var README_BYTES = 4e3;
+var MANIFEST_BYTES = 2e3;
+var MAX_DEPTH = 8;
+var SCAN_CEILING_FACTOR = 10;
+var MAX_FILES_READ = 400;
+var MAX_READ_BYTES = 2 * 1024 * 1024;
+function posix(path) {
+  return path.split(sep).join("/");
+}
+function walk(root) {
+  const files = [];
+  let truncated = false;
+  const visit = (dir, depth) => {
+    if (depth > MAX_DEPTH || files.length >= MAX_FILES_WALKED) {
+      truncated = true;
+      return;
+    }
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (files.length >= MAX_FILES_WALKED) {
+        truncated = true;
+        return;
+      }
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+        visit(join(dir, entry.name), depth + 1);
+      } else if (entry.isFile()) {
+        files.push(posix(relative(root, join(dir, entry.name))));
+      }
+    }
+  };
+  try {
+    if (!statSync(root).isDirectory()) return { files: [], truncated: false };
+  } catch {
+    return { files: [], truncated: false };
+  }
+  visit(root, 0);
+  return { files, truncated };
+}
+function readText(path, limit = Number.MAX_SAFE_INTEGER) {
+  let raw;
+  try {
+    if (statSync(path).size > MAX_READ_BYTES) return "";
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+  if (raw.includes("\0")) return "";
+  return raw.length > limit ? raw.slice(0, limit) : raw;
+}
+function skippedForSize(path) {
+  try {
+    return statSync(path).size > MAX_READ_BYTES;
+  } catch {
+    return false;
+  }
+}
+var COMMENT_RE = /(?:^|\s)(?:\/\/|#|\/\*|\*)\s*(TODO|FIXME|HACK)\b[:\s]?(.*)$/;
+function collectComments(root, files) {
+  const ceiling = MAX_COMMENTS * SCAN_CEILING_FACTOR;
+  const kept = [];
+  let total = 0;
+  let read = 0;
+  let skipped = 0;
+  let bounded = false;
+  for (const rel of files) {
+    const dot = rel.lastIndexOf(".");
+    if (dot < 0 || !SOURCE_EXT.has(rel.slice(dot))) continue;
+    if (total >= ceiling || read >= MAX_FILES_READ) {
+      bounded = true;
+      break;
+    }
+    const full = join(root, rel);
+    if (skippedForSize(full)) {
+      skipped += 1;
+      continue;
+    }
+    read += 1;
+    const text = readText(full);
+    if (text === "") continue;
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+      const match = COMMENT_RE.exec(lines[i]);
+      if (match === null) continue;
+      total += 1;
+      if (kept.length >= MAX_COMMENTS) continue;
+      const body = match[2].trim().slice(0, MAX_COMMENT_LINE);
+      kept.push(`${rel}:${i + 1}  ${match[1]} ${body}`.trimEnd());
+    }
+  }
+  return { kept, total, bounded, skippedForSize: skipped };
+}
+function hasTest(base, testNames) {
+  return testNames.has(`${base}.test`) || testNames.has(`${base}.spec`) || testNames.has(`test_${base}`) || testNames.has(`${base}_test`) || testNames.has(base);
+}
+function collectUntested(files) {
+  const testNames = /* @__PURE__ */ new Set();
+  for (const rel of files) {
+    const name = rel.slice(rel.lastIndexOf("/") + 1);
+    const stem = name.replace(/\.[^.]+$/, "");
+    if (/(^|[./_-])(test|spec)([./_-]|$)/i.test(rel)) {
+      testNames.add(stem);
+      testNames.add(stem.replace(/\.(test|spec)$/i, ""));
+    }
+  }
+  const ceiling = MAX_UNTESTED * SCAN_CEILING_FACTOR;
+  const kept = [];
+  let total = 0;
+  let bounded = false;
+  for (const rel of files) {
+    const dot = rel.lastIndexOf(".");
+    if (dot < 0 || !SOURCE_EXT.has(rel.slice(dot))) continue;
+    if (/(^|[./_-])(test|spec)([./_-]|$)/i.test(rel)) continue;
+    const stem = rel.slice(rel.lastIndexOf("/") + 1).replace(/\.[^.]+$/, "");
+    if (/^(index|main|types|constants)$/i.test(stem)) continue;
+    if (hasTest(stem, testNames)) continue;
+    if (total >= ceiling) {
+      bounded = true;
+      break;
+    }
+    total += 1;
+    if (kept.length < MAX_UNTESTED) kept.push(rel);
+  }
+  return { kept, total, bounded, skippedForSize: 0 };
+}
+function sectionHeader(title, total, kept, options = {}) {
+  const bound = options.bounded === true ? "+" : "";
+  const skipped = options.skippedForSize ?? 0;
+  const note = skipped > 0 ? ` (${skipped} file(s) too large to read)` : "";
+  const counts = kept < total || options.bounded === true ? `(${total}${bound} found, showing ${kept})` : `(${total})`;
+  return `### ${title} ${counts}${note}`;
+}
+function fileHeader(name, text, limit) {
+  if (text.length < limit) return `### ${name}`;
+  return `### ${name} (clipped to first ${Math.round(limit / 1e3)} KB)`;
+}
+function assemble(sections, walkTruncated) {
+  const parts = walkTruncated ? sections.concat(
+    "[walk truncated \u2014 this workspace is deeper or larger than one scan walks; files below the depth or count limit were never examined]"
+  ) : sections;
+  const joined = parts.join("\n\n");
+  if (joined.length <= DIGEST_BYTE_CAP) {
+    return { digest: joined, truncated: walkTruncated };
+  }
+  const marker = "\n\n[digest truncated \u2014 the workspace is larger than one scan can carry]";
+  return { digest: joined.slice(0, DIGEST_BYTE_CAP - marker.length) + marker, truncated: true };
+}
+function buildDigest(root) {
+  const { files, truncated } = walk(root);
+  const sections = [];
+  let sectionTruncated = false;
+  const tree = files.slice(0, MAX_TREE_ENTRIES);
+  if (tree.length > 0) {
+    if (tree.length < files.length) sectionTruncated = true;
+    sections.push(`${sectionHeader("Files", files.length, tree.length)}
+${tree.join("\n")}`);
+  }
+  const readmeName = files.find((f) => /^readme(\.md|\.txt)?$/i.test(f));
+  if (readmeName !== void 0) {
+    const raw = readText(join(root, readmeName), README_BYTES);
+    const text = raw.trim();
+    if (text !== "") {
+      if (raw.length >= README_BYTES) sectionTruncated = true;
+      sections.push(`${fileHeader(readmeName, raw, README_BYTES)}
+${text}`);
+    }
+  }
+  const manifest = files.find((f) => f === "package.json");
+  if (manifest !== void 0) {
+    const raw = readText(join(root, manifest), MANIFEST_BYTES);
+    const text = raw.trim();
+    if (text !== "") {
+      if (raw.length >= MANIFEST_BYTES) sectionTruncated = true;
+      sections.push(`${fileHeader("package.json", raw, MANIFEST_BYTES)}
+${text}`);
+    }
+  }
+  const comments = collectComments(root, files);
+  if (comments.kept.length > 0 || comments.skippedForSize > 0) {
+    if (comments.kept.length < comments.total || comments.bounded || comments.skippedForSize > 0) sectionTruncated = true;
+    sections.push(
+      sectionHeader(
+        "Unresolved comments (TODO/FIXME/HACK)",
+        comments.total,
+        comments.kept.length,
+        { bounded: comments.bounded, skippedForSize: comments.skippedForSize }
+      ) + (comments.kept.length > 0 ? "\n" + comments.kept.join("\n") : "")
+    );
+  }
+  const untested = collectUntested(files);
+  if (untested.kept.length > 0) {
+    if (untested.kept.length < untested.total || untested.bounded) sectionTruncated = true;
+    sections.push(
+      sectionHeader(
+        "Untested modules (name-based hint, not a coverage run)",
+        untested.total,
+        untested.kept.length,
+        { bounded: untested.bounded }
+      ) + "\n" + untested.kept.join("\n")
+    );
+  }
+  return assemble(sections, truncated || sectionTruncated);
+}
+export {
+  DIGEST_BYTE_CAP,
+  buildDigest
+};

package/lib/suggest.js

@@ -0,0 +1,93 @@
+// src/types.ts
+var PRIORITIES = ["p0", "p1", "p2", "p3"];
+var DEFAULT_PRIORITY = "p2";
+function toPriority(value) {
+  return typeof value === "string" && PRIORITIES.includes(value) ? value : DEFAULT_PRIORITY;
+}
+var MAX_TEXT = 500;
+var MAX_DESC = 5e3;
+var MAX_LABEL = 60;
+var SUGGESTIONS_DIR = ".dsh";
+var SUGGESTIONS_FILE = `${SUGGESTIONS_DIR}/suggestions.json`;
+function makeRunId(now = Date.now(), rand = Math.random) {
+  return `${now.toString(36)}${Math.floor(rand() * 1e6).toString(36)}`;
+}
+function suggestionsFileFor(runId) {
+  return `${SUGGESTIONS_DIR}/suggestions-${runId}.json`;
+}
+var MAX_SUGGESTIONS = 12;
+
+// src/suggest.ts
+function composeScanPrompt(digest, excludeTitles, runId) {
+  const parts = [
+    "# Propose work for this codebase",
+    "You are reviewing a workspace to propose concrete next tasks. Base every suggestion on the evidence below \u2014 do not speculate about code you cannot see.",
+    "Look for: unresolved TODO/FIXME/HACK comments, features the docs promise but the code does not implement, and modules with no tests.",
+    "## Evidence",
+    digest
+  ];
+  const exclusions = excludeTitles.map((t) => t.trim()).filter((t) => t.length > 0);
+  if (exclusions.length > 0) {
+    parts.push(
+      "## Already planned \u2014 do NOT suggest these or close variants of them",
+      exclusions.map((t) => `- ${t}`).join("\n")
+    );
+  }
+  parts.push(
+    "## Output",
+    `Write ONLY a JSON array to \`${suggestionsFileFor(runId)}\` (create the directory if needed).`,
+    'Each element: {"title": string, "rationale": string, "priority": "p0"|"p1"|"p2"|"p3", "evidence": string}',
+    "`evidence` is a `file:line` pointer where one exists; omit it otherwise.",
+    `Produce at most ${MAX_SUGGESTIONS} suggestions. Write the file and stop \u2014 do not implement anything.`
+  );
+  return parts.join("\n\n");
+}
+function unfence(raw) {
+  const open = /```[ \t]*[A-Za-z0-9_-]*[ \t]*\r?\n?/.exec(raw);
+  if (open === null) return raw;
+  const lead = raw.slice(0, open.index);
+  if (lead.includes("[") || lead.includes("{")) return raw;
+  const body = raw.slice(open.index + open[0].length);
+  const close = body.lastIndexOf("```");
+  return close === -1 ? raw : body.slice(0, close);
+}
+function parseSuggestions(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(unfence(raw));
+  } catch (cause) {
+    return { ok: false, error: `the scan wrote invalid JSON: ${cause instanceof Error ? cause.message : String(cause)}` };
+  }
+  const list = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.suggestions) ? parsed.suggestions : void 0;
+  if (list === void 0) {
+    return { ok: false, error: "the scan did not write a list of suggestions" };
+  }
+  const suggestions = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of list) {
+    if (entry === null || typeof entry !== "object") continue;
+    const row = entry;
+    const title = typeof row.title === "string" ? row.title.trim() : "";
+    if (title.length === 0) continue;
+    const stored = title.slice(0, MAX_TEXT);
+    const key = stored.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const evidence = typeof row.evidence === "string" ? row.evidence.trim().slice(0, MAX_LABEL) : "";
+    suggestions.push({
+      title: stored,
+      rationale: typeof row.rationale === "string" ? row.rationale.trim().slice(0, MAX_DESC) : "",
+      priority: toPriority(row.priority),
+      // Absent optional fields are ABSENT KEYS, never '', matching TodoItem.
+      ...evidence.length > 0 ? { evidence } : {}
+    });
+    if (suggestions.length >= MAX_SUGGESTIONS) break;
+  }
+  return { ok: true, suggestions };
+}
+export {
+  composeScanPrompt,
+  makeRunId,
+  parseSuggestions,
+  suggestionsFileFor
+};

package/lib/typert.host.js

@@ -37,6 +37,26 @@ var replaceResultSchema = z.union([
     list: todoListSchema
   })
 ]);
+var scanRequestSchema = z.object({ workspaceId: z.string() });
+var readSuggestionsRequestSchema = z.object({
+  workspaceId: z.string(),
+  runId: z.string()
+});
+var scanDigestResultSchema = z.object({
+  digest: z.string(),
+  truncated: z.boolean()
+});
+var suggestionSchema = z.object({
+  title: z.string(),
+  rationale: z.string(),
+  priority: z.enum(["p0", "p1", "p2", "p3"]),
+  evidence: z.string().optional()
+});
+var readSuggestionsResultSchema = z.object({
+  status: z.enum(["pending", "ready", "error"]),
+  suggestions: z.array(suggestionSchema).optional(),
+  error: z.string().optional()
+});
 var PACKAGE = "@dennisrongo/dsh-todo";
 function descriptor(method, request, result) {
   return {
@@ -72,7 +92,9 @@ var TODO_REMOTE = {
   package: PACKAGE,
   descriptors: [
     descriptor("list", listRequestSchema, listResultSchema),
-    descriptor("replace", replaceRequestSchema, replaceResultSchema)
+    descriptor("replace", replaceRequestSchema, replaceResultSchema),
+    descriptor("scanDigest", scanRequestSchema, scanDigestResultSchema),
+    descriptor("readSuggestions", readSuggestionsRequestSchema, readSuggestionsResultSchema)
   ]
 };
 
@@ -103,6 +125,18 @@ var TYPERT = {
             name: "replace",
             signature: "@Remote replace(request: TodoReplaceRequest): Promise<TodoReplaceResult>",
             summary: "Replace one workspace's list, guarded by the observed revision."
+          },
+          {
+            kind: "method",
+            name: "scanDigest",
+            signature: "@Remote scanDigest(request: SuggestScanRequest): Promise<ScanDigestResult>",
+            summary: "Build the bounded workspace evidence a scan session reasons over."
+          },
+          {
+            kind: "method",
+            name: "readSuggestions",
+            signature: "@Remote readSuggestions(request: ReadSuggestionsRequest): Promise<ReadSuggestionsResult>",
+            summary: "Read and consume whatever a scan session has written so far."
           }
         ],
         types: [
@@ -129,6 +163,29 @@ var TYPERT = {
           {
             name: "TodoReplaceResult",
             declaration: "export type TodoReplaceResult = { ok: true; list: TodoList } | { ok: false; code: 'revision-conflict'; list: TodoList };"
+          },
+          {
+            name: "SuggestScanRequest",
+            declaration: "export interface SuggestScanRequest {\n    workspaceId: string;\n}"
+          },
+          {
+            // `runId` is REQUIRED. A per-run result path is what stops a scan
+            // that timed out — archived, but never actually cancelled — writing
+            // its answer where the NEXT run reads it as fresh.
+            name: "ReadSuggestionsRequest",
+            declaration: "export interface ReadSuggestionsRequest {\n    workspaceId: string;\n    runId: string;\n}"
+          },
+          {
+            name: "ScanDigestResult",
+            declaration: "export interface ScanDigestResult {\n    digest: string;\n    truncated: boolean;\n}"
+          },
+          {
+            name: "Suggestion",
+            declaration: "export interface Suggestion {\n    title: string;\n    rationale: string;\n    priority: TodoPriority;\n    evidence?: string;\n}"
+          },
+          {
+            name: "ReadSuggestionsResult",
+            declaration: "export interface ReadSuggestionsResult {\n    status: 'pending' | 'ready' | 'error';\n    suggestions?: Suggestion[];\n    error?: string;\n}"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dennisrongo/dsh-todo",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Todo list for DeepSeek Harness (dsh) — a per-workspace task list persisted on disk by the host",
   "type": "module",
   "license": "MIT",
@@ -34,7 +34,7 @@
   "scripts": {
     "build": "node build/build.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "node build/build.mjs && node test/smoke.mjs && node test/context-probe.mjs && node test/launch-effect.mjs && node test/launch-lifecycle.mjs && node test/cli.test.mjs && node test/cli-integration.mjs",
+    "test": "node build/build.mjs && node test/smoke.mjs && node test/context-probe.mjs && node test/launch-effect.mjs && node test/launch-lifecycle.mjs && node test/suggest-lifecycle.mjs && node test/suggest.test.mjs && node test/scan.test.mjs && node test/cli.test.mjs && node test/cli-integration.mjs",
     "test:icons": "node test/icon-probe.mjs",
     "test:modal": "node test/modal-probe.mjs",
     "test:cli": "node test/cli.test.mjs",