@wrongstack/tools 0.313.0 → 0.313.1

package/dist/chunk-EMRGN4KM.js

@@ -0,0 +1,170 @@
+import {
+  ensureInsideRoot,
+  safeResolveReal
+} from "./chunk-D33S4RQG.js";
+
+// src/document.ts
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+var documentTool = {
+  name: "document",
+  category: "Project",
+  description: "DEPRECATED \u2014 read-only preview stub that lists undocumented symbols as `skipped` candidates. It never writes files and does not generate real docstrings. If the auto-doc plugin is enabled, use its `auto_doc` tool (with `dry_run: true` to preview) instead.",
+  usageHint: "Deprecated: this tool only lists undocumented symbols with placeholder comments \u2014 it does not generate real JSDoc/TSDoc and writes nothing. When the auto-doc plugin is enabled, prefer its `auto_doc` tool (`dry_run: true` for previewing, without it for writing).",
+  permission: "auto",
+  mutating: false,
+  timeoutMs: 3e4,
+  capabilities: ["fs.read"],
+  icon: "document",
+  inputSchema: {
+    type: "object",
+    properties: {
+      target: {
+        type: "string",
+        enum: ["file", "function", "class", "type", "all"],
+        description: "What to document"
+      },
+      path: {
+        type: "string",
+        description: "Specific file path to document"
+      },
+      files: {
+        type: "string",
+        description: "File(s) to process: single path, comma-separated list, or glob"
+      },
+      style: {
+        type: "string",
+        enum: ["jsdoc", "tsdoc", "block"],
+        description: "Documentation style (default: jsdoc)"
+      },
+      cwd: { type: "string", description: "Working directory (default: cwd)" }
+    }
+  },
+  async execute(input, ctx) {
+    const cwd = input.cwd ? await safeResolveReal(input.cwd, ctx) : ctx.cwd;
+    const style = input.style ?? "jsdoc";
+    const results = [];
+    let filesProcessed = 0;
+    let itemsDocumented = 0;
+    const fileList = input.files ? await resolveFiles(
+      Array.isArray(input.files) ? input.files.join(",") : input.files,
+      cwd,
+      ctx
+    ) : input.path ? [await safeResolveReal(input.path, ctx)] : [];
+    for (const absPath of fileList) {
+      try {
+        const content = await fs.readFile(absPath, "utf8");
+        filesProcessed++;
+        const processed = processFile(
+          content,
+          absPath,
+          style,
+          input.overwrite ?? false,
+          input.target ?? "all"
+        );
+        results.push(...processed);
+        itemsDocumented += processed.filter((r) => r.status === "documented").length;
+      } catch (e) {
+        results.push({
+          path: absPath,
+          name: absPath.split("/").pop() ?? absPath,
+          signature: "",
+          docstring: "",
+          status: "error",
+          error: e instanceof Error ? e.message : String(e)
+        });
+      }
+    }
+    return {
+      files_processed: filesProcessed,
+      items_documented: itemsDocumented,
+      results,
+      style
+    };
+  }
+};
+async function resolveFiles(filesInput, cwd, ctx) {
+  const files = filesInput.split(",");
+  const resolved = [];
+  for (const f of files) {
+    const entry = f.trim();
+    if (!entry) continue;
+    let absPath;
+    try {
+      absPath = ensureInsideRoot(path.resolve(cwd, entry), ctx);
+    } catch {
+      continue;
+    }
+    try {
+      const stat2 = await fs.stat(absPath);
+      if (stat2.isFile()) resolved.push(absPath);
+    } catch {
+    }
+  }
+  return resolved;
+}
+function processFile(content, absPath, _style, _overwrite, target) {
+  const results = [];
+  const functionRegex = /(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/g;
+  const arrowRegex = /(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\(([^)]*)\)\s*=>/g;
+  const classRegex = /class\s+(\w+)/g;
+  const typeRegex = /(?:type|interface)\s+(\w+)\s*[=<]/g;
+  const allMatches = [];
+  if (target === "all" || target === "function") {
+    for (const m of content.matchAll(functionRegex)) {
+      if (!m[1]) continue;
+      allMatches.push({
+        name: m[1],
+        sig: m[2] ?? "",
+        type: "function",
+        line: content.slice(0, m.index).split("\n").length
+      });
+    }
+    for (const m of content.matchAll(arrowRegex)) {
+      if (!m[1]) continue;
+      allMatches.push({
+        name: m[1],
+        sig: m[2] ?? "",
+        type: "arrow",
+        line: content.slice(0, m.index).split("\n").length
+      });
+    }
+  }
+  if (target === "all" || target === "class") {
+    for (const m of content.matchAll(classRegex)) {
+      if (!m[1]) continue;
+      allMatches.push({
+        name: m[1],
+        sig: "",
+        type: "class",
+        line: content.slice(0, m.index).split("\n").length
+      });
+    }
+  }
+  if (target === "all" || target === "type") {
+    for (const m of content.matchAll(typeRegex)) {
+      if (!m[1]) continue;
+      allMatches.push({
+        name: m[1],
+        sig: m[0] ?? "",
+        type: "type",
+        line: content.slice(0, m.index).split("\n").length
+      });
+    }
+  }
+  for (const m of allMatches) {
+    results.push({
+      path: absPath,
+      name: m.name,
+      signature: m.sig,
+      docstring: `/** ${m.name} - documented at line ${m.line} */`,
+      status: "skipped"
+    });
+  }
+  return results;
+}
+
+export {
+  documentTool
+};
+//# sourceMappingURL=chunk-EMRGN4KM.js.map