@aprimediet/codewalker 1.0.0 → 1.2.0

package/src/libs/dts.test.ts

@@ -0,0 +1,269 @@
+/**
+ * Tests for libs/dts.ts — .d.ts symbol extraction.
+ *
+ * These are PURE unit tests (fixture strings only, no I/O).
+ * Test every export form listed in §10 of the v1.2 plan.
+ */
+
+import { describe, it, expect } from "vitest";
+import { extractDtsSymbols } from "./dts.ts";
+import type { LibSymbol } from "../types.ts";
+
+/**
+ * Helper: run extractDtsSymbols and return sorted results for deterministic assertions.
+ */
+function extract(source: string, lib = "test-lib", version = "1.0.0"): LibSymbol[] {
+  return extractDtsSymbols(source, lib, version).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+describe("extractDtsSymbols", () => {
+  // ── function forms ────────────────────────────────────────────
+  it("extracts `export declare function`", () => {
+    const src = `export declare function createMiddleware<E>(handler: Hono): MiddlewareHandler;\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("createMiddleware");
+    expect(result[0]!.kind).toBe("function");
+    expect(result[0]!.signature).toContain("createMiddleware");
+    expect(result[0]!.lib).toBe("test-lib");
+    expect(result[0]!.version).toBe("1.0.0");
+  });
+
+  it("extracts `export function` (without declare)", () => {
+    const src = `export function greet(name: string): string;\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("greet");
+    expect(result[0]!.kind).toBe("function");
+  });
+
+  it("extracts generic function `export function f<T>(...)`", () => {
+    const src = `export function identity<T>(arg: T): T;\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("identity");
+    expect(result[0]!.kind).toBe("function");
+  });
+
+  // ── const forms ───────────────────────────────────────────────
+  it("extracts `export declare const`", () => {
+    const src = `export declare const BASE_URL: string;\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("BASE_URL");
+    expect(result[0]!.kind).toBe("const");
+  });
+
+  it("extracts `export const` (without declare)", () => {
+    const src = `export const TIMEOUT_MS: number = 5000;\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("TIMEOUT_MS");
+    expect(result[0]!.kind).toBe("const");
+  });
+
+  // ── class forms ───────────────────────────────────────────────
+  it("extracts `export declare class`", () => {
+    const src = `export declare class Router { handle(): void; }\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("Router");
+    expect(result[0]!.kind).toBe("class");
+    expect(result[0]!.signature).toContain("Router");
+  });
+
+  it("extracts `export class` (without declare)", () => {
+    const src = `export class Database { constructor(path: string); }\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("Database");
+    expect(result[0]!.kind).toBe("class");
+  });
+
+  it("extracts `export abstract class`", () => {
+    const src = `export abstract class Serializer { abstract serialize(data: unknown): string; }\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("Serializer");
+    expect(result[0]!.kind).toBe("class");
+  });
+
+  // ── interface ─────────────────────────────────────────────────
+  it("extracts `export interface`", () => {
+    const src = `export interface User { id: string; name: string; }\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("User");
+    expect(result[0]!.kind).toBe("interface");
+  });
+
+  // ── type ──────────────────────────────────────────────────────
+  it("extracts `export type`", () => {
+    const src = `export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("JsonValue");
+    expect(result[0]!.kind).toBe("type");
+  });
+
+  it("extracts `export type` with generic parameter", () => {
+    const src = `export type Result<T> = { ok: true; value: T } | { ok: false; error: string };\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("Result");
+    expect(result[0]!.kind).toBe("type");
+  });
+
+  // ── enum ──────────────────────────────────────────────────────
+  it("extracts `export declare enum`", () => {
+    const src = `export declare enum Color { Red, Green, Blue }\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("Color");
+    expect(result[0]!.kind).toBe("enum");
+  });
+
+  it("extracts `export enum` (without declare)", () => {
+    const src = `export enum Direction { Up, Down, Left, Right }\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("Direction");
+    expect(result[0]!.kind).toBe("enum");
+  });
+
+  // ── namespace ─────────────────────────────────────────────────
+  it("extracts `export declare namespace`", () => {
+    const src = `export declare namespace Util { function parse(s: string): any; }\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("Util");
+    expect(result[0]!.kind).toBe("namespace");
+  });
+
+  it("extracts `export namespace` (without declare)", () => {
+    const src = `export namespace Config { const port: number; }\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("Config");
+    expect(result[0]!.kind).toBe("namespace");
+  });
+
+  // ── re-exports ────────────────────────────────────────────────
+  it("extracts re-export `export { a, b as c } from \"...\"`", () => {
+    const src = `export { parse, stringify as format } from "./serializer";\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(2);
+    expect(result[0]!.name).toBe("format");
+    expect(result[0]!.kind).toBe("reexport");
+    expect(result[1]!.name).toBe("parse");
+    expect(result[1]!.kind).toBe("reexport");
+  });
+
+  it("extracts re-export `export { a, b }` (local module)", () => {
+    const src = `export { readFile, writeFile };\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(2);
+    expect(result[0]!.name).toBe("readFile");
+    expect(result[0]!.kind).toBe("reexport");
+    expect(result[1]!.name).toBe("writeFile");
+    expect(result[1]!.kind).toBe("reexport");
+  });
+
+  it("extracts `export * from` as a single re-export entry", () => {
+    const src = `export * from "./helpers";\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("*");
+    expect(result[0]!.kind).toBe("reexport");
+  });
+
+  // ── export default ────────────────────────────────────────────
+  it("extracts `export default function`", () => {
+    const src = `export default function createApp(opts?: Options): App;\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("default");
+    expect(result[0]!.kind).toBe("function");
+  });
+
+  it("extracts `export default class`", () => {
+    const src = `export default class Logger { log(...args: unknown[]): void; }\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("default");
+    expect(result[0]!.kind).toBe("class");
+  });
+
+  it("extracts `export default {…}` as const kind", () => {
+    const src = `export default { name: "app", version: "1.0" };\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe("default");
+    // Object literal default — kind "const" is a reasonable fallback
+    expect(result[0]!.kind).toBe("const");
+  });
+
+  // ── JSDoc / leading comments ──────────────────────────────────
+  it("captures leading JSDoc as doc and first line as summary", () => {
+    const src = [
+      '/** Create a typed middleware handler.',
+      ' * Use this to wrap Hono handlers with middleware. */',
+      'export declare function createMiddleware<E>(handler: Hono): MiddlewareHandler;',
+    ].join("\n") + "\n";
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.doc).toContain("Create a typed middleware handler");
+    expect(result[0]!.summary).toContain("Create a typed middleware handler");
+  });
+
+  it("sets summary to empty when no JSDoc", () => {
+    const src = `export declare function noDoc(): void;\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.summary).toBe("");
+  });
+
+  // ── non-exported declarations are ignored ─────────────────────
+  it("ignores non-exported declarations", () => {
+    const src = `declare function internal(): void;\nfunction privateHelper(): void;\nconst secret = "hidden";\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(0);
+  });
+
+  // ── multiple symbols in one file ──────────────────────────────
+  it("extracts multiple symbols from a .d.ts file", () => {
+    const src = [
+      `export interface User { id: string; }`,
+      `export declare function fetchUser(id: string): Promise<User>;`,
+      `export const MAX_RETRIES = 3;`,
+      `export enum Status { Active, Inactive }`,
+    ].join("\n");
+    const result = extract(src);
+    expect(result).toHaveLength(4);
+  });
+
+  // ── signature trimming ────────────────────────────────────────
+  it("trims trailing `{` from the signature", () => {
+    const src = `export interface User { id: string; name: string; }\n`;
+    const result = extract(src);
+    expect(result[0]!.signature).not.toMatch(/\{/);
+  });
+
+  // ── empty / no exports ────────────────────────────────────────
+  it("returns empty array for empty source", () => {
+    expect(extract("")).toHaveLength(0);
+  });
+
+  it("returns empty array for source with no export declarations", () => {
+    const src = `type Internal = string;\nconst secret = 42;\n`;
+    expect(extract(src)).toHaveLength(0);
+  });
+
+  // ── default export with JSDoc ─────────────────────────────────
+  it("captures JSDoc for default export", () => {
+    const src = `/** Main application factory. */\nexport default function createApp(opts: Options): App;\n`;
+    const result = extract(src);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.doc).toContain("Main application factory");
+  });
+});

package/src/libs/dts.ts

@@ -0,0 +1,213 @@
+/**
+ * .d.ts symbol extraction — regex/line-based, PURE (no I/O).
+ *
+ * Extracts top-level exported declarations from a `.d.ts` source string.
+ * Modeled on src/extract/regex.ts. Returns LibSymbol[] for a given library.
+ *
+ * Handles these export forms:
+ *   export declare function|const|class|enum|namespace
+ *   export function|const|class|interface|type|enum|namespace
+ *   export abstract class
+ *   export { a, b as c } from "..."   (reexport)
+ *   export { a, b }                    (local reexport)
+ *   export * from "..."                (star reexport → name: "*")
+ *   export default …                   (name: "default")
+ *
+ * Non-exported declarations are ignored. Leading JSDoc is captured.
+ */
+
+import type { LibSymbol, SymbolKind } from "../types.ts";
+import { extractDocComment } from "../extract/docs.ts";
+
+/**
+ * Extract top-level exported symbols from a .d.ts source string.
+ *
+ * @param source - Full .d.ts file content.
+ * @param lib - Library name.
+ * @param version - Installed version.
+ * @returns Array of extracted LibSymbol objects.
+ */
+export function extractDtsSymbols(
+  source: string,
+  lib: string,
+  version: string,
+): LibSymbol[] {
+  const lines = source.split("\n");
+  const symbols: LibSymbol[] = [];
+  let inBlockComment = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i] as string;
+    const trimmed = rawLine.trim();
+
+    // Track block comments
+    if (inBlockComment) {
+      if (trimmed.includes("*/")) inBlockComment = false;
+      continue;
+    }
+    if (trimmed.startsWith("/*") || trimmed.startsWith("/**")) {
+      if (!trimmed.includes("*/")) inBlockComment = true;
+      continue;
+    }
+    if (trimmed.startsWith("//")) continue;
+    if (!trimmed) continue;
+
+    // ── Named exports: export [declare] [abstract] <kind> <name> ──
+    const namedExport = tryExtractNamedExport(trimmed, lines, i, lib, version, source);
+    if (namedExport) {
+      symbols.push(namedExport);
+      continue;
+    }
+
+    // ── export default … (name always "default") ──
+    const defaultExport = tryExtractDefaultExport(trimmed, lines, i, lib, version, source);
+    if (defaultExport) {
+      symbols.push(defaultExport);
+      continue;
+    }
+
+    // ── Re-exports: export { … } or export * from … ──
+    const reExport = tryExtractReexport(trimmed, lines, i, lib, version, source);
+    if (reExport) {
+      symbols.push(...reExport);
+      continue;
+    }
+  }
+
+  return symbols;
+}
+
+/**
+ * Try to extract a named export declaration (function, const, class, interface, type, enum, namespace).
+ */
+function tryExtractNamedExport(
+  trimmed: string,
+  lines: string[],
+  i: number,
+  lib: string,
+  version: string,
+  source: string,
+): LibSymbol | null {
+  // Order matters: more specific before less specific.
+  // Each pattern: regex with named-kind capture, and a name capture group index.
+  const patterns: Array<{ regex: RegExp; kind: SymbolKind; nameIdx: number }> = [
+    // function: export [declare] [abstract] [async] function [<T>] name
+    { regex: /^export\s+(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?function\s+(?:<[^>]+>\s+)?(\w+)/, kind: "function", nameIdx: 1 },
+    // class: export [declare] [abstract] class name
+    { regex: /^export\s+(?:declare\s+)?(?:abstract\s+)?class\s+(\w+)/, kind: "class", nameIdx: 1 },
+    // interface: export interface name
+    { regex: /^export\s+interface\s+(\w+)/, kind: "interface", nameIdx: 1 },
+    // type: export type name [<...>] =
+    { regex: /^export\s+type\s+(\w+)/, kind: "type", nameIdx: 1 },
+    // enum: export [declare] enum name
+    { regex: /^export\s+(?:declare\s+)?enum\s+(\w+)/, kind: "enum", nameIdx: 1 },
+    // namespace: export [declare] namespace name
+    { regex: /^export\s+(?:declare\s+)?namespace\s+(\w+)/, kind: "namespace", nameIdx: 1 },
+    // const/let/var: export [declare] const name
+    { regex: /^export\s+(?:declare\s+)?(?:const|let|var)\s+(\w+)/, kind: "const", nameIdx: 1 },
+  ];
+
+  for (const p of patterns) {
+    const m = trimmed.match(p.regex);
+    if (m?.[p.nameIdx]) {
+      return makeSymbol(lines, i, p.kind, m[p.nameIdx]!, lib, version, source);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Try to extract `export default …`.
+ * Name is always "default". Kind is determined by what follows:
+ * function → "function", class → "class", object/expr → "const".
+ */
+function tryExtractDefaultExport(
+  trimmed: string,
+  lines: string[],
+  i: number,
+  lib: string,
+  version: string,
+  source: string,
+): LibSymbol | null {
+  if (!trimmed.startsWith("export default")) return null;
+
+  let kind: SymbolKind = "const";
+
+  if (/^export\s+default\s+(?:async\s+)?function\s/.test(trimmed)) {
+    kind = "function";
+  } else if (/^export\s+default\s+(?:abstract\s+)?class\s/.test(trimmed)) {
+    kind = "class";
+  } else if (/^export\s+default\s+interface\s/.test(trimmed)) {
+    kind = "interface";
+  }
+
+  return makeSymbol(lines, i, kind, "default", lib, version, source);
+}
+
+/**
+ * Try to extract re-export declarations:
+ *   export { a, b as c } [from "..."]
+ *   export * from "..."
+ */
+function tryExtractReexport(
+  trimmed: string,
+  lines: string[],
+  i: number,
+  lib: string,
+  version: string,
+  source: string,
+): LibSymbol[] | null {
+  // export { a, b as c } [from "..."]
+  const braceReexport = trimmed.match(/^export\s+\{([^}]+)\}(?:\s+from\s+["'][^"']*["'])?\s*;?\s*$/);
+  if (braceReexport) {
+    const names = braceReexport[1]!.split(",").map(s => s.trim()).filter(Boolean);
+    return names.map((entry) => {
+      const aliasMatch = entry.match(/^(\w+)\s+as\s+(\w+)$/);
+      const name = aliasMatch?.[2] ?? entry;
+      return makeSymbol(lines, i, "reexport", name, lib, version, source);
+    });
+  }
+
+  // export * from "..."
+  if (/^export\s+\*\s+from\s+["'][^"']*["']\s*;?\s*$/.test(trimmed)) {
+    return [makeSymbol(lines, i, "reexport", "*", lib, version, source)];
+  }
+
+  return null;
+}
+
+/**
+ * Build a LibSymbol from a declaration line.
+ * Signature is the declaration line with the body (from `{` onward) stripped.
+ */
+function makeSymbol(
+  lines: string[],
+  lineIndex: number,
+  kind: SymbolKind,
+  name: string,
+  lib: string,
+  version: string,
+  source: string,
+): LibSymbol {
+  const rawLine = (lines[lineIndex] as string).trim();
+
+  // Signature: first line, strip everything from the first `{` onward
+  const sigStart = rawLine.indexOf("{");
+  const signature = (sigStart >= 0 ? rawLine.slice(0, sigStart) : rawLine).trim();
+
+  // Capture JSDoc
+  const doc = extractDocComment(source, lineIndex + 1);
+  const summary = (doc.split("\n")[0] || "").trim();
+
+  return {
+    lib,
+    version,
+    name,
+    kind,
+    signature,
+    doc,
+    summary,
+    card_path: "",
+  };
+}