Fix: Make all method overloads get properly inherited into child classes (#150)

Author: ShukantPal

common/changes/@webdoc/model/fix-inherited-overloads_2022-02-19-21-21.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@webdoc/model",
+      "comment": "Support for advanced variants in query API. For example, \"ns.className#method[params[0][dataType] = string]\" to get a specific method overload!",
+      "type": "none"
+    }
+  ],
+  "packageName": "@webdoc/model",
+  "email": "[email protected]"
+}

common/changes/@webdoc/parser/fix-inherited-overloads_2022-02-19-21-21.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@webdoc/parser",
+      "comment": "Fix inheritance of overloaded methods. Prior to this fix, only the first overload was automatically inherited.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@webdoc/parser",
+  "email": "[email protected]"
+}

packages/webdoc-model/index.js.flow

@@ -1,9 +1,10 @@
 declare module "@webdoc/model" {
   import type {Doc, BaseDoc} from "@webdoc/types";
 
-  declare function createDoc(name?: string, type?: string, options?: any): BaseDoc;
-  declare function childDoc(lname: string, scope: BaseDoc): ?BaseDoc;
-  declare function addChildDoc<T: BaseDoc>(doc: T, scope: BaseDoc): T;
-  declare function doc(path: string | string[], root: BaseDoc): ?BaseDoc;
-  declare function addDoc<T: BaseDoc>(doc: BaseDoc, root: BaseDoc): ?T;
+  declare export function createDoc(name?: string, type?: string, options?: any): BaseDoc;
+  declare export function childDoc(lname: string, scope: BaseDoc): ?BaseDoc;
+  declare export function addChildDoc<T: BaseDoc>(doc: T, scope: BaseDoc): T;
+  declare export function doc(path: string | string[], root: BaseDoc): ?BaseDoc;
+  declare export function addDoc<T: BaseDoc>(doc: BaseDoc, root: BaseDoc): ?T;
+  declare export function mangled(doc: Doc): string;
 }

packages/webdoc-model/src/doc.js

@@ -1,14 +1,6 @@
 // @flow
 
-import type {
-  BaseDoc,
-  Doc,
-  DocLink,
-  DocType,
-  PackageDoc,
-  RootDoc,
-  TutorialDoc,
-} from "@webdoc/types";
+import type {BaseDoc, Doc, DocLink, DocType, PackageDoc, RootDoc, TutorialDoc} from "@webdoc/types";
 import {nanoid} from "nanoid";
 
 export const CANONICAL_SEPARATOR = /([.#~$])/g;
@@ -345,6 +337,22 @@ export function cloneDoc<T: Doc>(doc: T): T {
   });
 }
 
+/**
+ * Mangle the document name. If two documents have the same mangled name, then they shouldn't be
+ * siblings (indicating a duplication).
+ *
+ * @param {Doc} doc
+ * @return {string} - The mangled string name.
+ */
+export function mangled(doc: Doc): string {
+  if (doc.type === "MethodDoc") {
+    return `${doc.type}:${doc.name}:${
+      doc.params.map((p) => p.dataType ? p.dataType[0] : "unknown").join("-")}`;
+  }
+
+  return `${doc.type}:${doc.name}`;
+}
+
 /**
  * You can pass this to traverse too.
  */

packages/webdoc-model/src/query/parse.js

@@ -1,19 +1,13 @@
 // @flow
 // This file parses a raw query into a query model, as typed in types.js
 
-import type {
-  QueryExpr,
-  StepExpr,
-  StepType,
-  VariantCondition,
-  VariantExpr,
-} from "./types";
+import type {Op, QueryExpr, StepExpr, StepType, VariantCondition, VariantExpr} from "./types";
 
 // Regex to match step expression delimiters.
 const STEP_EXPR_DELIMITER = /(?:[.][.][.])|(?:[.#~])/g;
 
 // Regex to match variant expressions: [contents]
-const VARIANT_EXPR = /\[([^\]]+)\]/g;
+const VARIANT_EXPR = /\[([^\n]+)\]$/g;
 
 // Condition operators
 const OP = /(?:=)|(?:>=)|(?:<=)|(?:>)|(?:<)/g;
@@ -23,10 +17,10 @@ function parseCondition(condition: string): VariantCondition {
   const opPattern = new RegExp(OP).exec(condition);
 
   const op = opPattern ? opPattern[0] : "";
-  const [attribute, value] = condition.split(OP);
+  const [attribute, value] = condition.split(OP).map((expr) => expr.trim());
 
   return {
-    op,
+    op: ((op: any): Op),
     attribute,
     value,
   };

packages/webdoc-model/src/query/query.js

@@ -1,7 +1,7 @@
 // @flow
 
 import type {Doc} from "@webdoc/types";
-import type {Query} from "./types";
+import type {QueryExpr} from "./types";
 import {parse} from "./parse";
 import {step} from "./step";
 import {variant} from "./variant";
@@ -14,14 +14,14 @@ import {variant} from "./variant";
  * @param {Doc} docTree - The root of the document tree to be queried.
  * @return {Doc[]} The list of documents matching the query.
  */
-export function query(queryExpr: string | Query, docTree: Doc): Doc[] {
+export function query(queryExpr: string | QueryExpr, docTree: Doc): Doc[] {
   queryExpr = typeof queryExpr === "string" ? parse(queryExpr) : queryExpr;
   let results: Doc[] = [docTree];
 
   queryExpr.steps.forEach((stepExpr) => {
     results = results
       .flatMap((doc) => step(stepExpr, doc))
-      .filter((doc) => variant(stepExpr.variant, doc));
+      .filter((doc) => stepExpr.variant ? variant(stepExpr.variant, doc) : true);
   });
 
   return results;

packages/webdoc-model/src/query/types.js

@@ -1,9 +1,11 @@
+// @flow
+
 export type Op =
   "=" |
   ">=" |
   "<=" |
   ">" |
-  ">" |
+  "<" |
   "";
 
 export type AttributeName = string;

packages/webdoc-model/src/query/variant.js

@@ -1,19 +1,44 @@
 // @flow
 
-import {VariantCondition, VariantExpr} from "./types";
+import type {VariantCondition, VariantExpr} from "./types";
 import type {Doc} from "@webdoc/types";
 
 const operatorEngines = {
-  "=": (a, b) => (a === b),
+  "=": (a, b) => {
+    // DataType comparison
+    if (Array.isArray(a) && a.template && typeof b === "string") {
+      return a[0] === b;
+    }
+
+    return a === b;
+  },
   ">=": (a, b) => (a >= b),
   "<=": (a, b) => (a <= b),
   ">": (a, b) => (a > b),
   "<": (a, b) => (a < b),
+  "": (a, b) => true,
 };
 
+const SUBINDEX = /([^\n]+)\[([^\n]+)\]$/;
+
+function attribute(doc: any, attrib: string): any {
+  const result = attrib.match(SUBINDEX);
+
+  if (result !== null) {
+    const [, parentAttribute, index] = result;
+    const parentValue = attribute(doc, parentAttribute);
+
+    if (typeof parentValue === "object" && typeof index === "string") {
+      return parentValue[index];
+    }
+  }
+
+  return doc[attrib];
+}
+
 function condition(conditionClause: VariantCondition, doc: Doc): boolean {
-  const attributeValue = doc[conditionClause.attribute];
-  const conditionValue = conditionClause.value;
+  const attributeValue: any = attribute(doc, conditionClause.attribute);
+  const conditionValue: any = conditionClause.value;
 
   return operatorEngines[conditionClause.op](attributeValue, conditionValue);
 }

packages/webdoc-model/test/query/query.js

@@ -0,0 +1,40 @@
+const {
+  addChildDoc,
+  createDoc,
+  createRootDoc,
+  createSimpleKeywordType,
+  query,
+} = require("../../lib");
+
+const expect = require("chai").expect;
+
+describe("@webdoc/model:query", function() {
+  const documentTree = createRootDoc();
+  const nsDoc = addChildDoc(createDoc("ns", "NSDoc"), documentTree);
+  const parentClassDoc = addChildDoc(createDoc("ParentClass", "ClassDoc"), nsDoc);
+
+  addChildDoc(createDoc("invoke", "MethodDoc", {
+    params: [{
+      identifier: "arg0",
+      dataType: createSimpleKeywordType("number"),
+      description: "Arg 0",
+    }],
+  }), parentClassDoc);
+  addChildDoc(createDoc("invoke", "MethodDoc", {
+    params: [{
+      identifier: "arg0",
+      dataType: createSimpleKeywordType("string"),
+      description: "Arg 0",
+    }],
+  }), parentClassDoc);
+
+  it("should discriminate based on parameter data type variant", function() {
+    const m1Result = query("ns.ParentClass#invoke[params[0][dataType] = number]", documentTree);
+    const m2Result = query("ns.ParentClass#invoke[params[0][dataType] = string]", documentTree);
+
+    expect(m1Result.length).to.be.greaterThan(0);
+    expect(m2Result.length).to.be.greaterThan(0);
+    expect(m1Result[0].params[0].dataType[0]).to.equal("number");
+    expect(m2Result[0].params[0].dataType[0]).to.equal("string");
+  });
+});

packages/webdoc-parser/src/transformer/mod-discover-members.js

@@ -3,7 +3,7 @@
 // The discover-members mod imports member symbols from extended classes, implemented interfaces,
 // and mixed mixins.
 
-import {addChildDoc, cloneDoc} from "@webdoc/model";
+import {addChildDoc, cloneDoc, mangled} from "@webdoc/model";
 import type {Doc} from "@webdoc/types";
 
 // The set of docs that discoverMembers has run on
@@ -48,13 +48,15 @@ function discoverMembers(doc: Doc, depsChain = new Set<Doc>()): void {
 
   // This maps symbol names to the members of doc, so that the same symbol is not
   // inherited/overriden multiple times.
-  const memberMap: { [id: string]: any } = {};
+  const membersByMangledName: { [id: string]: any } = {};
+  const membersByName: { [id: string]: any } = {};
 
   // Prevent overridding symbols from being replaced by adding them beforehand.
   for (let i = 0; i < doc.members.length; i++) {
     const directMember = doc.members[i];
 
-    memberMap[directMember.name] = directMember;
+    membersByMangledName[mangled(directMember)] = directMember;
+    membersByName[directMember.name] = directMember;
   }
 
   const parents = [];
@@ -83,6 +85,7 @@ function discoverMembers(doc: Doc, depsChain = new Set<Doc>()): void {
 
     for (let i = 0; i < parent.members.length; i++) {
       const member = parent.members[i];
+      const memberMangled = mangled(member);
 
       // Only methods/properties/events are inheritable
       if (member.type !== "MethodDoc" &&
@@ -98,14 +101,23 @@ function discoverMembers(doc: Doc, depsChain = new Set<Doc>()): void {
       }
 
       // Parent symbols are hidden by inherited/implemented symbols
-      if (memberMap[member.name]) {
-        memberMap[member.name].overrides = member;
+      // Use mangled-map to try to find the most specific override
+      if (membersByMangledName[memberMangled]) {
+        membersByMangledName[memberMangled].overrides = member;
+        continue;
+      }
+      // TODO: We might want to skip setting "overrides" in this case if it already overrides a
+      //  more important / primary signature.
+      // Otherwise find by name
+      // If the child class has another member with a different signature but same number
+      if (membersByName[member.name]) {
+        membersByName[member.name].overrides = member;
         continue;
       }
 
-      memberMap[member.name] = member;
-
+      // Only add an inherited member if the child has no member with the same name
       const temp = cloneDoc(member);
+      membersByMangledName[memberMangled] = temp;
 
       temp.overrides = false;
       temp.inherited = true;