@xyd-js/sources 0.0.1-xyd.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @xyd-js/sources
+
+## 0.0.1-xyd.0
+
+### Patch Changes
+
+- refactor, tweaks and ui changes
+- Updated dependencies
+  - @xyd-js/uniform@0.1.0-xyd.11

package/README.md

@@ -0,0 +1,3 @@
+# @xyd-js/sources
+
+Automatic documentation from code sources, for xyd.

package/TODO.md

@@ -0,0 +1,6 @@
+1. use doc extractors:
+* go - godoc
+* python - https://github.com/mkdocstrings/griffe
+* js - https://github.com/TypeStrong/typedoc
+
+2. issues with: https://github.com/TypeStrong/typedoc/blob/3a3976da192126139c36dd711ab636f840d0c0ce/src/lib/application.ts#L51

package/dist/example.cjs

@@ -0,0 +1,642 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// test-cmd/index.ts
+var fs3 = __toESM(require("fs"), 1);
+var path2 = __toESM(require("path"), 1);
+var TypeDoc = __toESM(require("typedoc"), 1);
+
+// src/TypeDocTransformer.ts
+var fs2 = __toESM(require("fs"), 1);
+var path = __toESM(require("path"), 1);
+var import_typedoc = require("typedoc");
+
+// src/SignatureText.ts
+var ts = __toESM(require("typescript"), 1);
+var fs = __toESM(require("fs"), 1);
+var printer = ts.createPrinter({ removeComments: true });
+var SignatureTextLoader = class {
+  constructor(sourcePath) {
+    const source = fs.readFileSync(sourcePath, "utf-8");
+    this.sourceFile = ts.createSourceFile(
+      sourcePath,
+      source,
+      ts.ScriptTarget.Latest,
+      true
+    );
+  }
+};
+var MultiSignatureLoader = class {
+  constructor() {
+    this.loaders = /* @__PURE__ */ new Map();
+  }
+  load(path3) {
+    if (this.loaders.has(path3)) {
+      return this.loaders.get(path3);
+    }
+    const loader = new SignatureTextLoader(path3);
+    this.loaders.set(path3, loader);
+    return loader;
+  }
+};
+function signatureTextByLine(sign, targetLine) {
+  return signatureText.call(sign, targetLine);
+}
+function signatureSourceCodeByLine(sign, targetLine) {
+  return signatureSourceCode.call(sign, targetLine);
+}
+function signatureText(targetLine) {
+  const sourceFile = this.sourceFile;
+  const signatureNode = findSignatureNode.call(
+    this,
+    sourceFile,
+    [targetLine]
+  );
+  if (!signatureNode) {
+    console.error("(signatureText): `signatureNode` is empty, something went wrong");
+    return;
+  }
+  const printableSignatureNode = nodeToPrintableSignatureNode(signatureNode);
+  if (!printableSignatureNode) {
+    console.error("(signatureText): cannot convert `signatureNode` to `printableSignatureNode`");
+    return;
+  }
+  return printer.printNode(ts.EmitHint.Unspecified, printableSignatureNode, sourceFile).trim();
+}
+function findSignatureNode(node, targetLines) {
+  let isSourceFile = false;
+  if (node === node.getSourceFile()) {
+    isSourceFile = true;
+  }
+  if (!isSourceFile && isNodeAtLine(node, targetLines, this.sourceFile)) {
+    return node;
+  }
+  let signatureNode;
+  ts.forEachChild(node, (n) => {
+    if (signatureNode) {
+      return;
+    }
+    signatureNode = findSignatureNode.call(this, n, targetLines);
+  });
+  return signatureNode;
+}
+function signatureSourceCode(targetLine) {
+  const sourceFile = this.sourceFile;
+  const signatureNode = findSignatureNode.call(
+    this,
+    sourceFile,
+    [targetLine]
+  );
+  if (!signatureNode) {
+    console.error("(signatureSourceCode): `signatureNode` is empty, something went wrong");
+    return;
+  }
+  const start = signatureNode.getStart(sourceFile);
+  const end = signatureNode.getEnd();
+  return sourceFile.text.substring(start, end).trim();
+}
+function nodeToPrintableSignatureNode(node) {
+  let resp;
+  if (ts.isFunctionDeclaration(node)) {
+    resp = ts.factory.updateFunctionDeclaration(
+      node,
+      node.modifiers,
+      node.asteriskToken,
+      node.name,
+      node.typeParameters,
+      node.parameters,
+      node.type,
+      void 0
+    );
+  } else if (ts.isClassDeclaration(node)) {
+    resp = ts.factory.updateClassDeclaration(
+      node,
+      node.modifiers,
+      node.name,
+      node.typeParameters,
+      node.heritageClauses,
+      []
+    );
+  } else if (ts.isInterfaceDeclaration(node)) {
+    resp = ts.factory.updateInterfaceDeclaration(
+      node,
+      node.modifiers,
+      node.name,
+      node.typeParameters,
+      node.heritageClauses,
+      []
+    );
+  } else if (ts.isEnumDeclaration(node)) {
+    resp = ts.factory.updateEnumDeclaration(
+      node,
+      node.modifiers,
+      node.name,
+      []
+    );
+  } else if (ts.isTypeAliasDeclaration(node)) {
+    resp = ts.factory.updateTypeAliasDeclaration(
+      node,
+      node.modifiers,
+      node.name,
+      node.typeParameters,
+      node.type
+    );
+  }
+  if (!resp) {
+    console.error("(nodeToPrintableSignatureNode): resp is empty, something went wrong");
+    return;
+  }
+  return resp;
+}
+function isNodeAtLine(node, lines, sf) {
+  const { line: startLine } = sf.getLineAndCharacterOfPosition(node.getStart());
+  return lines.includes(startLine + 1);
+}
+
+// src/TypeDocTransformer.ts
+var TypeDocSignatureTextLoader = class extends MultiSignatureLoader {
+  constructor(project, packagePathMap) {
+    super();
+    this.project = project;
+    this.packagePathMap = packagePathMap;
+  }
+  signatureText(id, line) {
+    const loader = this.getSignatuerLoader(id);
+    if (!loader) {
+      return;
+    }
+    const signTxt = signatureTextByLine(loader, line);
+    if (!signTxt) {
+      console.warn("(TypeDocSignatureTextLoader.signatureText): Signature text is empty", id);
+      return;
+    }
+    return signTxt;
+  }
+  signatureSourceCode(id, line) {
+    const loader = this.getSignatuerLoader(id);
+    if (!loader) {
+      return;
+    }
+    const sourceCode = signatureSourceCodeByLine(loader, line);
+    if (!sourceCode) {
+      console.warn("(TypeDocSignatureTextLoader.signatureSourceCode): Source code is empty", id);
+      return;
+    }
+    return sourceCode;
+  }
+  getSignatuerLoader(id) {
+    const symbolMap = this.project.symbolIdMap[id];
+    if (!symbolMap) {
+      console.warn("(TypeDocSignatureTextLoader.getSignatuerLoader): Symbol not found", id);
+      return;
+    }
+    const fullPath = this.packagePathMap[id];
+    if (!fullPath) {
+      console.warn("(TypeDocSignatureTextLoader.getSignatuerLoader): Package path not found for symbol", symbolMap.packageName);
+      return;
+    }
+    const loader = this.load(fullPath);
+    if (!loader) {
+      console.warn("(TypeDocSignatureTextLoader.getSignatuerLoader): Loader not found", fullPath);
+      return;
+    }
+    return loader;
+  }
+};
+var Transformer = class {
+  constructor(rootPath, project, references = []) {
+    this.rootPath = rootPath;
+    this.project = project;
+    this.references = references;
+    this.packagePathMap = {};
+    const packagePathMap = this.createPackagePathMap();
+    if (packagePathMap) {
+      this.packagePathMap = packagePathMap;
+    }
+  }
+  createPackagePathMap() {
+    const packagePathMap = {};
+    const packageJsonPaths = this.findPackageJsonPaths(this.rootPath);
+    if (!packageJsonPaths.length) {
+      console.warn("(Transformer.createPackagePathMap): No package.json found in rootPath", this.rootPath);
+      return { packageMap: null, moduleRootMap: null };
+    }
+    for (const packageJsonPath of packageJsonPaths) {
+      const packageJson = JSON.parse(fs2.readFileSync(packageJsonPath, "utf-8"));
+      const packageName = packageJson.name;
+      const moduleRoot = path.dirname(packageJsonPath);
+      if (!packageName) {
+        console.warn("(Transformer.createPackagePathMap): Package name not found in package.json", packageJsonPath);
+        continue;
+      }
+      for (const id in this.project.symbolIdMap) {
+        const symbolMap = this.project.symbolIdMap[id];
+        if (symbolMap.packageName === packageName) {
+          const fullPath = path.join(moduleRoot, symbolMap.packagePath);
+          packagePathMap[Number.parseInt(id)] = fullPath;
+        }
+      }
+    }
+    return packagePathMap;
+  }
+  findPackageJsonPaths(dir) {
+    let results = [];
+    const list = fs2.readdirSync(dir);
+    for (const file of list) {
+      const filePath = path.join(dir, file);
+      const stat = fs2.statSync(filePath);
+      if (stat && stat.isDirectory()) {
+        results = results.concat(this.findPackageJsonPaths(filePath));
+      } else if (file === "package.json") {
+        results.push(filePath);
+      }
+    }
+    return results;
+  }
+};
+function typedocToUniform(rootPath, project) {
+  const references = [];
+  const transformer = new Transformer(
+    rootPath,
+    project,
+    references
+  );
+  const signatureTextLoader = new TypeDocSignatureTextLoader(
+    project,
+    transformer.packagePathMap
+  );
+  transformer.signatureTextLoader = signatureTextLoader;
+  if (project.kind !== import_typedoc.ReflectionKind.Project) {
+    throw new Error("Project reflection expected");
+  }
+  for (const child of project.children || []) {
+    if (!("kind" in child)) {
+      throw new Error("(typedocToUniform): Child reflection expected in project childrens");
+    }
+    if (typeof child.kind != "number") {
+      throw new Error("(typedocToUniform): Child reflection kind expected to be a number");
+    }
+    if (!child.kind) {
+      throw new Error("(typedocToUniform): Child reflection kind expected to be a valid ReflectionKind");
+    }
+    const kind = child.kind;
+    switch (kind) {
+      case import_typedoc.ReflectionKind.Module: {
+        const container = child;
+        for (const group of container.children || []) {
+          const ref = typedocGroupToUniform.call(
+            transformer,
+            group
+          );
+          if (!ref) {
+            continue;
+          }
+          ref.context = {
+            ...ref.context,
+            package: container.name
+          };
+          references.push(ref);
+        }
+        break;
+      }
+      case import_typedoc.ReflectionKind.Function:
+      case import_typedoc.ReflectionKind.Class: {
+        if (!child) {
+          throw new Error("(typedocToUniform): Function reflection expected to be a DeclarationReflection");
+        }
+        const ref = typedocGroupToUniform.call(
+          transformer,
+          child
+        );
+        if (!ref) {
+          break;
+        }
+        ref.context = {
+          ...ref.context,
+          package: project.name
+        };
+        references.push(ref);
+        break;
+      }
+      default: {
+        console.warn("(typedocToUniform): Another children project kind not supported", child.kind);
+      }
+    }
+  }
+  return references;
+}
+function typedocGroupToUniform(group) {
+  let ref;
+  switch (group.kind) {
+    case import_typedoc.ReflectionKind.Class: {
+      ref = jsClassToUniformRef.call(this, group);
+      break;
+    }
+    case import_typedoc.ReflectionKind.Function: {
+      ref = jsFunctionToUniformRef.call(this, group);
+      break;
+    }
+    default: {
+      console.warn("(typedocGroupToUniform): Unhandled reflection kind", group.kind);
+    }
+  }
+  return ref;
+}
+function jsClassToUniformRef(dec) {
+  var _a, _b, _c, _d;
+  const definitions = [];
+  const ref = {
+    title: `Class ${dec.name}`,
+    canonical: `class-${dec.name}`,
+    description: "",
+    context: {},
+    examples: {
+      groups: []
+    },
+    definitions
+  };
+  const declarationCtx = declarationUniformContext.call(this, dec);
+  if (declarationCtx) {
+    ref.context = {
+      ...ref.context,
+      ...declarationCtx
+    };
+  }
+  if (dec.comment) {
+    const description = commentToUniform(dec.comment);
+    const group = ((declarationCtx == null ? void 0 : declarationCtx.packageName.split("/")) || []).map((name) => `"${name}"`).join(",");
+    ref.description = `---
+title: ${dec.name} 
+group: [${group}, Classes]
+---
+${description}`;
+  }
+  {
+    const constructor = (_a = dec.children) == null ? void 0 : _a.find((child) => child.name === "constructor");
+    if ((_b = constructor == null ? void 0 : constructor.signatures) == null ? void 0 : _b[0]) {
+      const constructorDef = {
+        title: "Constructor",
+        properties: []
+      };
+      const constructorSign = constructor.signatures[0];
+      for (const param of constructorSign.parameters || []) {
+        if (!param.type) {
+          console.warn("(jsClassToUniformRef): Constructor parameter type not found", param.name);
+          continue;
+        }
+        let description = "";
+        if (param.comment) {
+          description = commentToUniform(param.comment);
+        }
+        constructorDef.properties.push({
+          name: param.name,
+          type: someTypeToUniformType(param.type),
+          description
+        });
+      }
+      definitions.push(constructorDef);
+    }
+  }
+  {
+    const methods = ((_c = dec.children) == null ? void 0 : _c.filter(
+      (child) => child.kind === import_typedoc.ReflectionKind.Method && child.name !== "constructor"
+    )) || [];
+    if (methods.length > 0) {
+      const methodsDef = {
+        title: "Methods",
+        properties: []
+      };
+      for (const method of methods) {
+        if (!((_d = method.signatures) == null ? void 0 : _d[0])) continue;
+        const methodSign = method.signatures[0];
+        let methodDesc = "";
+        if (methodSign.comment) {
+          methodDesc = commentToUniform(methodSign.comment);
+        }
+        methodsDef.properties.push({
+          name: method.name,
+          type: methodSign.type ? someTypeToUniformType(methodSign.type) : "void",
+          description: methodDesc
+        });
+      }
+      definitions.push(methodsDef);
+    }
+  }
+  return ref;
+}
+function jsFunctionToUniformRef(dec) {
+  const definitions = [];
+  const ref = {
+    title: `Function ${dec.name}`,
+    canonical: `fn-${dec.name}`,
+    description: "",
+    context: {},
+    examples: {
+      groups: []
+    },
+    definitions
+  };
+  const declarationCtx = declarationUniformContext.call(this, dec);
+  if (declarationCtx) {
+    ref.context = {
+      ...ref.context,
+      ...declarationCtx
+    };
+  }
+  const signatures = dec.signatures || [];
+  if (signatures.length > 1) {
+    console.error("(jsFunctionToUniformRef): Multiple signatures not supported for function declaration", dec.name);
+    return;
+  }
+  for (const sign of dec.signatures || []) {
+    {
+      if (sign.comment) {
+        const description = commentToUniform(sign.comment);
+        const group = ((declarationCtx == null ? void 0 : declarationCtx.packageName.split("/")) || []).map((name) => `"${name}"`).join(",");
+        ref.description = `---
+title: ${dec.name}
+group: [${group}, Functions]
+---
+${description}`;
+      }
+    }
+    {
+      const returnsUniformDef = {
+        title: "Returns",
+        properties: []
+      };
+      if (sign.type) {
+        let desc = "";
+        if (sign.comment) {
+          desc = returnCommentToUniform(sign.comment) || "";
+        }
+        returnsUniformDef.properties.push({
+          name: "",
+          type: someTypeToUniformType(sign.type),
+          description: desc
+        });
+      }
+      ref.definitions.push(returnsUniformDef);
+    }
+    {
+      const parametersUniformDef = {
+        title: "Parameters",
+        properties: []
+      };
+      for (const param of sign.parameters || []) {
+        if (!param.type) {
+          console.warn("(jsFunctionToUniformRef): Parameter type not found", param.name);
+          continue;
+        }
+        let description = "";
+        if (param.comment) {
+          description = commentToUniform(param.comment);
+        }
+        parametersUniformDef.properties.push({
+          name: param.name,
+          type: someTypeToUniformType(param.type),
+          description
+        });
+      }
+      ref.definitions.push(parametersUniformDef);
+    }
+  }
+  return ref;
+}
+function declarationUniformContext(dec) {
+  if (!dec.sources || !dec.sources.length) {
+    return;
+  }
+  if (dec.sources.length > 1) {
+    console.warn("(declarationUniformContext): Multiple sources not supported for function declaration", dec.name);
+    return;
+  }
+  const source = dec.sources[0];
+  if (!source.fileName) {
+    return;
+  }
+  const signTxt = this.signatureTextLoader.signatureText(
+    dec.id,
+    source.line
+  ) || "";
+  const sourceCode = this.signatureTextLoader.signatureSourceCode(
+    dec.id,
+    source.line
+  ) || "";
+  const symbolMap = this.project.symbolIdMap[dec.id];
+  if (!symbolMap) {
+    console.warn("(declarationUniformContext): Symbol not found", dec.id);
+    return;
+  }
+  const fileFullPath = symbolMap.packagePath;
+  return {
+    packageName: symbolMap.packageName,
+    fileName: source.fileName,
+    fileFullPath,
+    line: source.line,
+    col: source.character,
+    signatureText: {
+      code: signTxt,
+      lang: "ts"
+    },
+    sourcecode: {
+      code: sourceCode,
+      lang: "ts"
+    }
+  };
+}
+function someTypeToUniformType(someType) {
+  if (!("name" in someType)) {
+    console.warn("SomeType does not have name property", someType);
+    return "";
+  }
+  switch (someType.type) {
+    case "reference": {
+      return `<${someType.name}>`;
+    }
+    default: {
+      return someType.name;
+    }
+  }
+}
+function commentToUniform(comment) {
+  let desc = "";
+  for (const summary of (comment == null ? void 0 : comment.summary) || []) {
+    desc += `${summary.text}
+`;
+  }
+  return desc;
+}
+function returnCommentToUniform(comment) {
+  if (!comment.blockTags || !comment.blockTags.length) {
+    return;
+  }
+  let desc = "";
+  for (const tag of comment.blockTags) {
+    if (tag.tag === "@returns") {
+      for (const content of tag.content || []) {
+        desc += `${content.text}
+`;
+      }
+    }
+  }
+  return desc;
+}
+
+// test-cmd/index.ts
+async function generateDocs() {
+  const options = {
+    entryPoints: [
+      "example/package-a"
+      // "example/package-b",
+    ],
+    plugin: [
+      "typedoc-plugin-markdown"
+    ],
+    readme: "none",
+    disableSources: true,
+    entryPointStrategy: TypeDoc.EntryPointStrategy.Packages,
+    indexFormat: "table",
+    useCodeBlocks: true
+  };
+  const app = await TypeDoc.Application.bootstrapWithPlugins(options);
+  const project = await app.convert();
+  if (!project) {
+    throw new Error("Failed to generate documentation.");
+  }
+  const jsonOutput = await app.serializer.projectToObject(project, path2.resolve("./example"));
+  fs3.writeFileSync("docs.json", JSON.stringify(jsonOutput, null, 2));
+  await app.generateOutputs(project);
+  {
+    const projectRaw = fs3.readFileSync("docs.json", "utf-8");
+    const projectJson = JSON.parse(projectRaw);
+    const ref = typedocToUniform(
+      path2.resolve("./example"),
+      projectJson
+    );
+    fs3.writeFileSync("references_todo.json", JSON.stringify(ref, null, 2));
+  }
+}
+generateDocs().catch(console.error);
+//# sourceMappingURL=example.cjs.map