fix: class processing

src/generate.ts

@@ -1,10 +1,10 @@
 import Bluebird from "bluebird";
+import { promises as fs } from "fs";
+import { Cls, printer } from "./ir/ir";
 import { scrapeClassPage } from "./scrape/classes";
 import { scrapeConcepts } from "./scrape/concepts";
 import { scrapeDefines } from "./scrape/defines";
 import { ofUrl } from "./scrape/dom";
-import { printer } from "./ir/ir";
-import { promises as fs } from "fs";
 
 export const produce = async ({
   urls,
@@ -14,8 +14,21 @@ export const produce = async ({
   };
 }) => {
   const classLinks = await enumerateClassUrlsFromUrl(urls.apiRoot);
-  const classSchemas = await getClassesFromUrl(classLinks).then((pageSchemas) =>
-    pageSchemas.flat()
+  const nonDedupedclassSchemas = await getClassesFromUrl(
+    classLinks
+  ).then((pageSchemas) => pageSchemas.flat());
+  const classSchemas = Object.values(
+    nonDedupedclassSchemas.reduce((byName, curr) => {
+      if (byName[curr.name]) {
+        if (JSON.stringify(curr) !== JSON.stringify(byName[curr.name])) {
+          throw new Error(
+            `class ${curr.name} varies depending from where it is parsed! :|`
+          );
+        }
+      }
+      byName[curr.name] = curr;
+      return byName;
+    }, {} as Record<string, Cls>)
   );
   const [defines, concepts] = await Promise.all([
     getDefinesFromUrl(urls.apiRoot),
@@ -25,6 +38,7 @@ export const produce = async ({
     `/** @noSelfInFile */`,
     printer.print(defines),
     ...concepts.map(printer.print),
+    ...classSchemas.map(printer.print),
   ].join("\n");
   // const definitions = [
   //   ...classSchemas.map(({ schema, className }) => ({

src/ir/ir.ts

@@ -92,6 +92,7 @@ export type Type =
   | Any
   | And
   | Collection
+  | Cls
   | Field
   | Function
   | Intf
@@ -128,10 +129,12 @@ export type Property = {
 } & IRCommon<"property">;
 export const property = factory<Property>("property");
 
-export type Struct = {
+type StructLike = {
   name: string;
-  members: ClassMember[];
-} & IRCommon<"struct">;
+  members: Property[];
+};
+
+export type Struct = StructLike & IRCommon<"struct">;
 
 export const struct = factory<Struct>("struct");
 
@@ -142,10 +145,9 @@ export type Intf = {
 } & IRCommon<"interface">;
 export const intf = factory<Intf>("interface");
 
-export type ClassMember = Property | Function;
 export type Cls = {
   inherits?: Sym[];
-} & Omit<Struct, "__type"> &
+} & StructLike &
   IRCommon<"class">;
 export const cls = factory<Cls>("class");
 

src/ir/of-lua.ts

@@ -4,10 +4,12 @@ import {
   any,
   arr,
   bool,
+  fn,
   map,
   nil,
   num,
   optional,
+  param,
   str,
   sym,
   Type,
@@ -76,6 +78,24 @@ export const ofLua = (ltype_: string): Type => {
   if (unmodeled.includes(ltype)) {
     return any({});
   }
+  /**
+   * @todo
+   * docs sometimes yield just the word `function` with no type details :/.
+   * sometimes it does have mediocre type details. let's improve it
+   */
+  if (ltype === "function" || ltype.match(/function\([^)]*\)/)) {
+    return fn({
+      name: "fn",
+      parameters: [
+        param({
+          name: "args",
+          isVariadic: true,
+          type: any({}),
+        }),
+      ],
+      return: any({}),
+    });
+  }
   if (!definitionTypes.includes(ltype)) {
     definitionTypes.push(ltype.trim());
     console.warn(`:: Adding type ${ltype}`);

src/ir/printer.ts

@@ -38,6 +38,7 @@ export const printInner = (t: Type): string => {
         .join(" ")} }`;
       if (!t.isRoot) return inner;
       return `interface ${t.name} \n${inner} `;
+    case "class":
     case "struct":
       return `interface ${t.name} { \n  ${t.members
         .map((member) => {
@@ -48,8 +49,9 @@ export const printInner = (t: Type): string => {
       return `${t.text}`;
     case "union":
       return `(${t.members.map(print).join(" | ")})`;
-    case "number":
     case "nil":
+      return "null";
+    case "number":
     case "string":
     case "boolean":
     case "any":

src/scrape/classes.ts

@@ -5,7 +5,6 @@ import { asMarkdown, asUrlCorrectedMarkdown } from "../batteries/markdown";
 import { PageMeta } from "../interfaces";
 import {
   any,
-  ClassMember,
   Cls,
   cls,
   field,
@@ -16,6 +15,7 @@ import {
   optional,
   param,
   Param,
+  Property,
   property,
   sym,
   Type,
@@ -86,7 +86,8 @@ export const getParamFromRow = (el: IElement): Param => {
     const [typeStr, description] = r1.split(":").map(trim);
     return param({
       description,
-      name,
+      // handle TS keyword edge case - keywords in typings are not permitted as key name
+      name: name === "function" ? "fn" : name,
       type: ofLua(typeStr),
     });
   } else {
@@ -113,8 +114,15 @@ export const parseParam = (el: IElement, i: number): Param => {
       nameAndOptional = "";
     }
     let [name] = nameAndOptional.split("(optional)").map(trim);
+    // case: "Table with the following fields: <desc>\n\n<ul>..."
+    if (name.startsWith("Table with")) {
+      name = "tbl";
+    }
     const isOptional = name !== nameAndOptional;
     const members = Array.from(fieldsUl.children).reduce((acc, el, j) => {
+      // @todo consider supporting `optional?` properties for "Additional entity-specific parameters" entries
+      // these entities do not have great narrowing properties, ready to be parsed from the HTML
+      if (el.textContent.startsWith("Additional")) return acc;
       const prm = parseParam(el, j);
       acc[prm.name] = field({ type: prm.type, description: prm.description });
       return acc;
@@ -129,7 +137,10 @@ export const parseParam = (el: IElement, i: number): Param => {
   return getParamFromRow(el);
 };
 
-export const parseImplEl = (implEl: IElement, description: string) => {
+export const parseMemberFnFromImplEl = (
+  implEl: IElement,
+  description: string
+) => {
   const id = implEl.id;
   if (!id) throw new Error("unable to find id");
   const name = id.split(".")[id.split(".").length - 1];
@@ -187,16 +198,22 @@ export const parseImplEl = (implEl: IElement, description: string) => {
   }
   const returnType = ofLua(returnTypeText.trim());
   const isReturnDescriptionPermittingNil = returnDescription.match("or nil");
-  return fn({
-    description,
+  return property({
     name,
-    parameters: params,
-    return: isReturningNil
-      ? nil({ description: "" })
-      : isReturnDescriptionPermittingNil
-      ? union({ members: [returnType, nil({ description: "" })], description })
-      : returnType,
-    returnDescription,
+    description,
+    type: fn({
+      name,
+      parameters: params,
+      return: isReturningNil
+        ? nil({ description: "" })
+        : isReturnDescriptionPermittingNil
+        ? union({
+            members: [returnType, nil({ description: "" })],
+            description,
+          })
+        : returnType,
+      returnDescription,
+    }),
   });
 };
 
@@ -213,19 +230,22 @@ const parseMemberFunction = (
   const implAnchor = query(el, "a", "missing impl anchor");
   // fast parse when there are no args
   if (el.textContent.includes("()")) {
-    return fn({
-      description,
+    return property({
       name: implAnchor.textContent,
-      parameters: [],
-      return: el.textContent.includes("→")
-        ? ofLua(
-            query(
-              el,
-              ".return-type",
-              "unable to find return type"
-            ).textContent.trim()
-          )
-        : nil({ description: "" }),
+      description,
+      type: fn({
+        name: implAnchor.textContent,
+        parameters: [],
+        return: el.textContent.includes("→")
+          ? ofLua(
+              query(
+                el,
+                ".return-type",
+                "unable to find return type"
+              ).textContent.trim()
+            )
+          : nil({ description: "" }),
+      }),
     });
   }
   // slow parse when no arg case fails
@@ -235,7 +255,7 @@ const parseMemberFunction = (
   if (!implEl) {
     throw new Error("missing impl el");
   }
-  return parseImplEl(implEl, description);
+  return parseMemberFnFromImplEl(implEl, description);
 };
 
 const parseMemberAttr = (
@@ -271,7 +291,7 @@ const parseMemberRow = (
   document: Document,
   row: IElement,
   pageMeta: PageMeta
-): ClassMember => {
+): Property => {
   const [signatureEl, descriptionEl] = row.children;
   if (!signatureEl) throw new Error("unable to find member signature el");
   const description = asUrlCorrectedMarkdown(
@@ -314,12 +334,8 @@ export const ofEl = (document: Document, el: IElement, pageMeta: PageMeta) => {
     it.classList.contains("brief-members")
   );
   if (!membersRootEl) throw new Error(`unable to find class member root el`);
-
-  const members = parseMemberRows(
-    document,
-    queryAll(membersRootEl, "tr"),
-    pageMeta
-  );
+  const memberRows = queryAll(membersRootEl, "tr");
+  const members = parseMemberRows(document, memberRows, pageMeta);
   return cls({
     name,
     description: getDescription(

src/scrape/concepts.ts

@@ -23,10 +23,6 @@ export const scrapeConcept = (el: IElement) => {
     name,
     description,
     members: fields.map((field) => {
-      if (testIsType(field.type, fn)) {
-        // @todo - did we just throw away a bunch of info? do we actually expect this case?
-        return field.type;
-      }
       return property(field);
     }),
   });

test/class-method.test.ts

@@ -1,27 +1,27 @@
 import ava, { TestInterface } from "ava";
-import { parseImplEl } from "../src/scrape/classes";
+import { parseMemberFnFromImplEl } from "../src/scrape/classes";
 import { getFixture } from "./fixture/snippets";
 
 const test = ava as TestInterface<{}>;
 
 test("parse method params - set_controller", async (t) => {
   const { el } = await getFixture("class-params-table-arg-set_controller.html");
-  const parsed = parseImplEl(el, "test-description");
+  const parsed = parseMemberFnFromImplEl(el, "test-description");
   t.snapshot(parsed);
 });
 
 test("parse method params - create_local_flying_text", async (t) => {
   const { el } = await getFixture(
     "class-params-table-arg-create_local_flying_text.html"
   );
-  const parsed = parseImplEl(el, "test-description");
+  const parsed = parseMemberFnFromImplEl(el, "test-description");
   t.snapshot(parsed);
 });
 
 test("parse method params - set_allows_action", async (t) => {
   const { el } = await getFixture(
     "class-params-mismatched-params-set_allows_action.html"
   );
-  const parsed = parseImplEl(el, "test-description");
+  const parsed = parseMemberFnFromImplEl(el, "test-description");
   t.snapshot(parsed);
 });