@elisra-devops/docgen-data-provider 0.4.6

package/src/modules/TicketsDataProvider.ts

@@ -0,0 +1,435 @@
+import { TFSServices } from "../helpers/tfs";
+import { Workitem } from "../models/tfs-data";
+import { Helper, suiteData, Links, Trace, Relations } from "../helpers/helper";
+import { Query, TestSteps } from "../models/tfs-data";
+import { QueryType } from "../models/tfs-data";
+import { QueryAllTypes } from "../models/tfs-data";
+import { Column } from "../models/tfs-data";
+import { value } from "../models/tfs-data";
+import { TestCase } from "../models/tfs-data";
+import * as xml2js from "xml2js";
+
+import logger from "../utils/logger";
+
+export default class TicketsDataProvider {
+  orgUrl: string = "";
+  token: string = "";
+  queriesList: Array<any> = new Array<any>();
+
+  constructor(orgUrl: string, token: string) {
+    this.orgUrl = orgUrl;
+    this.token = token;
+  }
+
+  async GetWorkItem(
+    project: string,
+    id: string
+  ): Promise<any> {
+    let url = `${this.orgUrl}${project}/_apis/wit/workitems/${id}?$expand=All`;
+    return TFSServices.getItemContent(url, this.token);
+  }
+  async GetLinksByIds(
+    project: string, 
+    ids: any
+  ) {
+    var trace: Array<Trace> = new Array<Trace>();
+    let wis = await this.PopulateWorkItemsByIds(ids, project);
+    let linksMap: any = await this.GetRelationsIds(wis);
+
+    let relations;
+    for (let i = 0; i < wis.length; i++) {
+      let traceItem: Trace; //= new Trace();
+      traceItem = await this.GetParentLink(project, wis[i]);
+
+      if (linksMap.get(wis[i].id).rels.length > 0) {
+        relations = await this.PopulateWorkItemsByIds(
+          linksMap.get(wis[i].id).rels,
+          project
+        );
+        traceItem.links = await this.GetLinks(project, wis[i], relations);
+      }
+      trace.push(traceItem);
+    }
+    return trace;
+  }
+  async GetParentLink(
+    project: string,
+    wi: any
+  ) {
+    let trace: Trace = new Trace();
+    if (wi != null) {
+      trace.id = wi.id;
+      trace.title = wi.fields["System.Title"];
+      trace.url = this.orgUrl + project + "/_workitems/edit/" + wi.id;
+      if (
+        wi.fields["System.CustomerId"] != null &&
+        wi.fields["System.CustomerId"] != undefined
+      ) {
+        trace.customerId = wi.fields["System.CustomerId"];
+      }
+    }
+    return trace;
+  }
+  async GetRelationsIds(
+    ids: any
+  ) {
+    let rel = new Map<string, Relations>();
+    try {
+      for (let i = 0; i < ids.length; i++) {
+        var link = new Relations();
+        link.id = ids[i].id;
+        if (ids[i].relations != null)
+          for (let j = 0; j < ids[i].relations.length; j++) {
+            if (ids[i].relations[j].rel != "AttachedFile") {
+              let index = ids[i].relations[j].url.lastIndexOf("/");
+              let id = ids[i].relations[j].url.substring(index + 1);
+              link.rels.push(id);
+            }
+          }
+        rel.set(ids[i].id, link);
+      }
+    } catch (e) {}
+    return rel;
+  }
+  async GetLinks(
+    project: string,
+    wi: any,
+    links: any
+  ) {
+    var linkList: Array<Links> = new Array<Links>();
+    for (let i = 0; i < wi.relations.length; i++) {
+      for (let j = 0; j < links.length; j++) {
+        let index = wi.relations[i].url.lastIndexOf("/");
+        let linkId = wi.relations[i].url.substring(index + 1);
+        if (linkId == links[j].id) {
+          var link = new Links();
+          link.type = wi.relations[i].rel;
+          link.id = links[j].id;
+          link.title = links[j].fields["System.Title"];
+          link.description = links[j].fields["System.Description"];
+          link.url = this.orgUrl + project + "/_workitems/edit/" + linkId;
+          linkList.push(link);
+          break;
+        }
+      }
+    }
+    return linkList;
+  }
+  // gets queries recursiv
+  async GetSharedQueries(
+    project: string,
+    path: string
+  ): Promise<any> {
+    let url;
+    try {
+      if (path == "")
+        url = `${this.orgUrl}${project}/_apis/wit/queries/Shared%20Queries?$depth=1`;
+      else
+        url = `${this.orgUrl}${project}/_apis/wit/queries/${path}?$depth=1`;
+      let queries: any = await TFSServices.getItemContent(url, this.token);
+      for (let i = 0; i < queries.children.length; i++)
+        if (queries.children[i].isFolder) {
+          this.queriesList.push(queries.children[i]);
+          await this.GetSharedQueries(project, queries.children[i].path);
+        } else {
+          this.queriesList.push(queries.children[i]);
+        }
+      return this.GetModeledQuery(this.queriesList);
+    } catch (e) {}
+  }
+  // get queris structured
+  GetModeledQuery(
+    list: Array<any>
+  ): Array<any> {
+    let queryListObject: Array<any> = [];
+    list.forEach((query) => {
+      let newObj = {
+        queryName: query.name,
+        wiql: query._links.wiql != null ? query._links.wiql : null,
+        id: query.id,
+      };
+      queryListObject.push(newObj);
+    });
+    return queryListObject;
+  }
+  // gets query results
+  async GetQueryResultsByWiqlHref(
+    wiqlHref: string,
+    project: string
+  ): Promise<any> {
+    try {
+      let results: any = await TFSServices.getItemContent(wiqlHref, this.token);
+      let modeledResult = await this.GetModeledQueryResults(results, project);
+      if (modeledResult.queryType == "tree") {
+        let levelResults: Array<Workitem> = Helper.LevelBuilder(
+          modeledResult,
+          modeledResult.workItems[0].fields[0].value
+        );
+        return levelResults;
+      }
+      return modeledResult.workItems;
+    } catch (e) {}
+  }
+  // gets query results
+  async GetQueryResultsByWiqlString(
+    wiql: string,
+    projectName: string
+  ): Promise<any> {
+    let res;
+    let url = `${this.orgUrl}${projectName}/_apis/wit/wiql?$top=2147483646&expand={all}`;
+    try {
+      res = await TFSServices.getItemContent(url, this.token, "post", {
+        query: wiql,
+      });
+    } catch (error) {
+      console.log(error);
+      return [];
+    }
+    return res;
+  }
+  async GetQueryResultById(
+    query: string,
+    project: string
+  ): Promise<any> {
+    var url = `${this.orgUrl}${project}/_apis/wit/queries/${query}`;
+    let querie: any = await TFSServices.getItemContent(url, this.token);
+    var wiql = querie._links.wiql;
+    return await this.GetQueryResultsByWiqlHref(wiql.href, project);
+  }
+
+  async PopulateWorkItemsByIds(
+    workItemsArray: any[] = [],
+    projectName: string = ""
+  ): Promise<any[]> {
+    let url = `${this.orgUrl}${projectName}/_apis/wit/workitemsbatch`;
+    let res: any[] = [];
+    let divByMax = Math.floor(workItemsArray.length / 200);
+    let modulusByMax = workItemsArray.length % 200;
+    //iterating
+    for (let i = 0; i < divByMax; i++) {
+      let from = i * 200;
+      let to = (i + 1) * 200;
+      let currentIds = workItemsArray.slice(from, to);
+      try {
+        let subRes = await TFSServices.getItemContent(url, this.token, "post", {
+          $expand: "Relations",
+          ids: currentIds,
+        });
+        res = [...res, ...subRes.value];
+      } catch (error) {
+        logger.error(`error populating workitems array`);
+        logger.error(JSON.stringify(error));
+        return [];
+      }
+    }
+    //compliting the rimainder
+    if (modulusByMax !== 0) {
+      try {
+        let currentIds = workItemsArray.slice(
+          workItemsArray.length - modulusByMax,
+          workItemsArray.length
+        );
+        let subRes = await TFSServices.getItemContent(url, this.token, "post", {
+          $expand: "Relations",
+          ids: currentIds,
+        });
+        res = [...res, ...subRes.value];
+      } catch (error) {
+        logger.error(`error populating workitems array`);
+        logger.error(JSON.stringify(error));
+        return [];
+      }
+    } //if
+
+    return res;
+  }
+  
+  async GetModeledQueryResults(
+    results: any,
+    project: string
+  ) {
+    let ticketsDataProvider = new TicketsDataProvider(
+      this.orgUrl,
+      this.token,
+    );
+    var queryResult: Query = new Query();
+    queryResult.asOf = results.asOf;
+    queryResult.queryResultType = results.queryResultType;
+    queryResult.queryType = results.queryType;
+    if (results.queryType == QueryType.Flat) {
+      //     //Flat Query
+      //TODo: attachment
+      //TODO:check if wi.relations exist
+      //TODO: add attachment to any list from 1
+      for (var j = 0; j < results.workItems.length; j++) {
+        let wi = await ticketsDataProvider.GetWorkItem(
+          project,
+          results.workItems[j].id
+        );
+
+        queryResult.workItems[j] = new Workitem();
+        queryResult.workItems[j].url = results.workItems[j].url;
+        queryResult.workItems[j].fields = new Array(results.columns.length);
+        if (wi.relations != null) {
+          queryResult.workItems[j].attachments = wi.relations;
+        }
+        var rel = new QueryAllTypes();
+        for (var i = 0; i < results.columns.length; i++) {
+          queryResult.columns[i] = new Column();
+          queryResult.workItems[j].fields[i] = new value();
+          queryResult.columns[i].name = results.columns[i].name;
+          queryResult.columns[i].referenceName =
+            results.columns[i].referenceName;
+          queryResult.columns[i].url = results.columns[i].url;
+          if (results.columns[i].referenceName.toUpperCase() == "SYSTEM.ID") {
+            queryResult.workItems[j].fields[i].value = wi.id.toString();
+            queryResult.workItems[j].fields[i].name = "ID";
+          } else if (
+            results.columns[i].referenceName.toUpperCase() ==
+              "SYSTEM.ASSIGNEDTO" &&
+            wi.fields[results.columns[i].referenceName] != null
+          )
+            queryResult.workItems[j].fields[i].value =
+              wi.fields[results.columns[i].referenceName].displayName;
+          else {
+            let s: string = wi.fields[results.columns[i].referenceName];
+            queryResult.workItems[j].fields[i].value =
+              wi.fields[results.columns[i].referenceName];
+            queryResult.workItems[j].fields[i].name = results.columns[i].name;
+          }
+        }
+      }
+    } //Tree Query
+    else {
+      this.BuildColumns(results, queryResult);
+      for (var j = 0; j < results.workItemRelations.length; j++) {
+        if (results.workItemRelations[j].target != null) {
+          let wiT = await ticketsDataProvider.GetWorkItem(
+            project,
+            results.workItemRelations[j].target.id
+          );
+          // var rel = new QueryAllTypes();
+          queryResult.workItems[j] = new Workitem();
+          queryResult.workItems[j].url = wiT.url;
+          queryResult.workItems[j].fields = new Array(results.columns.length);
+          if (wiT.relations != null) {
+            queryResult.workItems[j].attachments = wiT.relations;
+          }
+          // rel.q = queryResult;
+          for (i = 0; i < queryResult.columns.length; i++) {
+            //..  rel.q.workItems[j].fields[i] = new value();
+            queryResult.workItems[j].fields[i] = new value();
+            queryResult.workItems[j].fields[i].name =
+              queryResult.columns[i].name;
+            if (
+              results.columns[i].referenceName.toUpperCase() ==
+                "SYSTEM.ASSIGNEDTO" &&
+              wiT.fields[results.columns[i].referenceName] != null
+            )
+              queryResult.workItems[j].fields[i].value =
+                wiT.fields[results.columns[i].referenceName].displayName;
+            else
+              queryResult.workItems[j].fields[i].value =
+                wiT.fields[queryResult.columns[i].referenceName];
+            //}
+          }
+          if (results.workItemRelations[j].source != null)
+            queryResult.workItems[j].Source =
+              results.workItemRelations[j].source.id;
+        }
+      }
+    }
+    return queryResult;
+  }
+
+  BuildColumns(
+    results: any,
+    queryResult: Query
+  ) {
+    for (var i = 0; i < results.columns.length; i++) {
+      queryResult.columns[i] = new Column();
+      queryResult.columns[i].name = results.columns[i].name;
+      queryResult.columns[i].referenceName = results.columns[i].referenceName;
+      queryResult.columns[i].url = results.columns[i].url;
+    }
+  }
+
+  async GetIterationsByTeamName(
+    projectName: string,
+    teamName: string
+  ): Promise<any[]> {
+    let res: any;
+    let url;
+    if (teamName) {
+      url = `${this.orgUrl}${projectName}/${teamName}/_apis/work/teamsettings/iterations`;
+    } else {
+      url = `${this.orgUrl}${projectName}/_apis/work/teamsettings/iterations`;
+    }
+    res = await TFSServices.getItemContent(url, this.token, "get");
+    return res;
+  } //GetIterationsByTeamName
+
+  async CreateNewWorkItem(
+    projectName: string,
+    wiBody: any,
+    wiType: string,
+    byPass: boolean
+  ) {
+    let url = 
+    `${this.orgUrl}${projectName}/_apis/wit/workitems/$${wiType}?bypassRules=${String(byPass).toString()}`;
+    return TFSServices.getItemContent(url,this.token,"POST",wiBody,{"Content-Type": "application/json-patch+json"});
+    } //CreateNewWorkItem
+
+  async GetWorkitemAttachments(
+    project: string,
+    id: string
+  ) {
+    let attachmentList: Array<string> = [];
+    let ticketsDataProvider = new TicketsDataProvider(
+      this.orgUrl,
+      this.token,
+    );
+    try {
+      let wi = await ticketsDataProvider.GetWorkItem(project, id);
+      if (!wi.relations) return [];
+      await Promise.all(
+        wi.relations.map(async (relation: any) => {
+          if (relation.rel == "AttachedFile") {
+            let attachment = JSON.parse(JSON.stringify(relation));
+            attachment.downloadUrl = `${relation.url}/${relation.attributes.name}`;
+            attachmentList.push(attachment);
+          }
+        })
+      );
+      return attachmentList;
+    } catch (e) {
+      logger.error(`error fetching attachments for work item ${id}`);
+      logger.error(`${JSON.stringify(e)}`);
+      return [];
+    }
+  }
+
+  async GetWorkitemAttachmentsJSONData(
+    project: string,
+    attachmentId: string
+  ) {
+    let wiuRL =`${this.orgUrl}${project}/_apis/wit/attachments/${attachmentId}`;
+    let attachment = await TFSServices.getItemContent(wiuRL, this.token);
+    return attachment;
+  }
+
+  async UpdateWorkItem(
+    projectName: string,
+    wiBody: any,
+    workItemId: number,
+    byPass: boolean
+  ) {
+    let res: any;
+    let url: string = 
+    `${this.orgUrl}${projectName}/_apis/wit/workitems/${workItemId}?bypassRules=${String(byPass).toString()}`;
+    res = await TFSServices.getItemContent(url, this.token, "patch", wiBody, {
+      "Content-Type": "application/json-patch+json",
+    });
+    return res;
+  } //CreateNewWorkItem
+}

package/src/modules/test/gitDataProvider.test.ts

@@ -0,0 +1,207 @@
+import DgDataProviderAzureDevOps from "../..";
+
+require("dotenv").config();
+jest.setTimeout(60000);
+const orgUrl = process.env.ORG_URL;
+const token = process.env.PAT;
+
+const dgDataProviderAzureDevOps = new DgDataProviderAzureDevOps(orgUrl,token);
+
+
+describe("git module - tests", () => {
+  test("should return repo list for teamProject", async () => {
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let json: any = await gitDataProvider.GetTeamProjectGitReposList(
+      "tests"
+    );
+    expect(json).toBeDefined();
+  });
+  test("should return repo from repoid", async () => {
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let json: any = await gitDataProvider.GetGitRepoFromRepoId(
+      "68f2aee7-0864-458e-93ce-320303a080ed"
+    );
+    expect(json).toBeDefined();
+  });
+  test("should return repo by pullrequest id", async () => {
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let json: any = await gitDataProvider.GetGitRepoFromPrId(
+      73
+    );
+    expect(json.repository).toBeDefined();
+  });
+  test("should return commits by pullrequest & repo id", async () => {
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let json: any = await gitDataProvider.GetGitRepoFromPrId(73);
+    let commitJson: any = await gitDataProvider.GetPullRequestCommits(
+      json.repository.id,
+      73
+    );
+    expect(commitJson.value.length).toBeGreaterThan(0);
+  });
+  test("should return pullrequest threads", async () => {
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let json = await gitDataProvider.GetPullRequestComments(
+      "tests",
+      "68f2aee7-0864-458e-93ce-320303a080ed",
+      73
+    );
+    expect(json.count).toBeDefined;
+  });
+  test("should create pullrequest thread", async () => {
+    let data = {
+      comments: [
+        {
+          parentCommentId: 0,
+          content: "Should we add a comment about what this value means?",
+          commentType: 1,
+        },
+      ],
+      status: 1,
+      threadContext: {
+        filePath: "/assaf.txt",
+        leftFileEnd: null,
+        leftFileStart: null,
+        rightFileEnd: {
+          line: 2,
+          offset: 1,
+        },
+        rightFileStart: {
+          line: 2,
+          offset: 5,
+        },
+      },
+      pullRequestThreadContext: {
+        changeTrackingId: 1,
+        iterationContext: {
+          firstComparingIteration: 1,
+          secondComparingIteration: 1,
+        },
+      },
+    };
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let json = await gitDataProvider.CreatePullRequestComment(
+      "tests",
+      "68f2aee7-0864-458e-93ce-320303a080ed",
+      73,
+      data
+    );
+    expect(json.comment).toBeDefined;
+  });
+  test("should return commits with linked items in date range", async () => {
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let commitRange = await gitDataProvider.GetCommitsInDateRange(
+      "Azuretraining",
+      "b77bccb5-38de-4dca-9dcb-b0f8046bc045",
+      "2016-10-21T12:51:51Z",
+      "2024-10-24T12:51:51Z",
+      "main"
+    );
+    let items = await gitDataProvider.GetItemsInCommitRange(
+      "Azuretraining",
+      "b77bccb5-38de-4dca-9dcb-b0f8046bc045",
+      commitRange
+    );
+    expect(items[0].workItem).toBeDefined();
+  });
+  test("should return source trigger commit for pipline", async () => {
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let json = await gitDataProvider.GetCommitForPipeline(
+      "tests",
+      248
+    );
+    expect(json).toBe("59d59691ee002815e7aa774f0a90ef28a6e4708f");
+  });
+  test("should return commits in commit range", async () => {
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let json = await gitDataProvider.GetCommitsInCommitRange(
+      "tests",
+      "68f2aee7-0864-458e-93ce-320303a080ed",
+      "4ce7f96f74f10bb60d27d7180a8d1bd44da1ffac",
+      "e46f8023be49db94b5cf188b41f7ba9db6fd8274"
+    );
+    expect(json.count).toBeGreaterThan(0);
+  });
+  test("should return items linked in build range", async () => {
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let json = await gitDataProvider.GetItemsForPipelinesRange(
+      "tests",
+      244,
+      244
+    );
+    expect(json.length).toBeGreaterThan(0);
+  });
+  test("should return commits range between dates ", async () => {
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let json = await gitDataProvider.GetCommitsInDateRange(
+      "tests",
+      "68f2aee7-0864-458e-93ce-320303a080ed",
+      "2009-11-30T12:51:51Z",
+      "2021-11-30T12:51:51Z"
+    );
+    expect(json.count).toBeGreaterThanOrEqual(14);
+  });
+  test("should return all commits for repo ", async ()=>{
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let json = await gitDataProvider.GetCommitsForRepo(
+      "tests",  
+      "68f2aee7-0864-458e-93ce-320303a080ed",
+      "master"
+    );
+    expect(json.count).toBeGreaterThanOrEqual(0);
+  })
+  test("should return all pullrequests for repo ", async ()=>{
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let json = await gitDataProvider.GetPullRequestsForRepo(
+      "tests",
+      "68f2aee7-0864-458e-93ce-320303a080ed"
+    );
+    expect(json.count).toBeGreaterThanOrEqual(0);
+  })
+
+  test("should return all pullrequests for repo with Given PrId ", async ()=>{
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let json = await gitDataProvider.GetItemsInPullRequestRange(
+      "tests",
+      "68f2aee7-0864-458e-93ce-320303a080ed",
+      [73,74]
+      );
+    expect(json.count).toBeGreaterThanOrEqual(0);
+  })
+
+  test("should return branches of repository ", async ()=>{
+    let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+    let json = await gitDataProvider.GetRepoBranches(
+      "tests",
+      "68f2aee7-0864-458e-93ce-320303a080ed",
+      );
+    expect(json.count).toBeGreaterThanOrEqual(0);
+  })
+
+}); //describe
+
+test("should return pull requests in commit range without linked items", async () => {
+  let gitDataProvider = await dgDataProviderAzureDevOps.getGitDataProvider();
+
+  // Get the commit range using the date range
+  let commitRange = await gitDataProvider.GetCommitsInDateRange(
+    "Azuretraining",
+    "b77bccb5-38de-4dca-9dcb-b0f8046bc045",
+    "2023-7-21T12:51:51Z",
+    "2024-8-21T12:51:51Z",
+    "main"
+  );
+
+  // Use the new function to get pull requests without linked items
+  let pullRequests = await gitDataProvider.GetPullRequestsInCommitRangeWithoutLinkedItems(
+    "Azuretraining",
+    "b77bccb5-38de-4dca-9dcb-b0f8046bc045",
+    commitRange
+  );
+
+  // Print the pull requests
+  console.log("Pull Requests:", pullRequests);
+
+  expect(pullRequests).toBeDefined();
+  expect(pullRequests.length).toBeGreaterThan(0);
+});

package/src/modules/test/managmentDataProvider.test.ts

@@ -0,0 +1,34 @@
+import DgDataProviderAzureDevOps from "../..";
+
+require("dotenv").config();
+jest.setTimeout(60000);
+
+const orgUrl = process.env.ORG_URL;
+const token = process.env.PAT;
+const dgDataProviderAzureDevOps = new DgDataProviderAzureDevOps(orgUrl,token);
+
+
+describe("Common functions module - tests", () => {
+  test("should return all collecttion projects", async () => {
+    let managmentDataProvider = await dgDataProviderAzureDevOps.getMangementDataProvider();
+    let json = await managmentDataProvider.GetProjects();
+    expect(json.count).toBeGreaterThanOrEqual(1);
+  });
+  test("should return project by name", async () => {
+    let managmentDataProvider = await dgDataProviderAzureDevOps.getMangementDataProvider();
+    let json = await managmentDataProvider.GetProjectByName("tests");
+    expect(json.name).toBe("tests");
+  });
+  test("should return project by id", async () => {
+    let managmentDataProvider = await dgDataProviderAzureDevOps.getMangementDataProvider();
+    let json = await managmentDataProvider.GetProjectByID(
+      "45a48633-890c-42bb-ace3-148d17806857"
+    );
+    expect(json.name).toBe("tests");
+  });
+  test("should return all collecttion link types", async () => {
+    let managmentDataProvider = await dgDataProviderAzureDevOps.getMangementDataProvider();
+    let json = await managmentDataProvider.GetCllectionLinkTypes();
+    expect(json.count).toBeGreaterThan(1);
+  });
+}); //describe