zephyr-enterprise-tools 1.2.5 → 1.2.7

package/README.md

@@ -25,6 +25,7 @@ Comprehensive tools for Zephyr Enterprise - Release Readiness, Project Health, T
 | `test-trends` | Test execution trends over time |
 | `search-tests` | Search test cases by query |
 | `user-activity` | User activity and productivity metrics |
+| `user-trend` | Full audit log history for a user — every action across the system |
 | `execution-burndown` | Day-by-day execution burndown (remaining vs ideal) |
 
 ---
@@ -73,6 +74,7 @@ Use zephyr-enterprise-tools as an MCP (Model Context Protocol) server with your
 | `test_trends` | Get execution trends over time |
 | `search_test_cases` | Search test cases by query |
 | `user_activity` | Get user activity metrics |
+| `user_trend` | Full audit log history for a user — filter by date range, entity type, and operation |
 | `execution_burndown` | Day-by-day execution burndown chart data (remaining vs ideal) |
 
 ### Claude Desktop

package/mcp-server.js

@@ -20,12 +20,13 @@ import QualityGates from './zephyr-enterprise-tools.js';
 const TOOLS = [
   {
     name: 'release_readiness',
-    description: 'Run all 4 quality gates to assess release readiness. Returns GO, CONDITIONAL GO, or NO GO status.',
+    description: 'Run all 4 quality gates with calculation details and action items. Optionally scope Test Plan Analysis to a Zephyr ZQL expression. Returns GO, CONDITIONAL GO, or NO GO status.',
     inputSchema: {
       type: 'object',
       properties: {
         projectId: { type: 'number', description: 'Zephyr project ID' },
         releaseId: { type: 'number', description: 'Zephyr release ID' },
+        query: { type: 'string', description: 'Optional Zephyr ZQL expression for Test Plan Analysis, e.g. priority = "P1"' },
       },
       required: ['projectId', 'releaseId'],
     },
@@ -44,12 +45,13 @@ const TOOLS = [
   },
   {
     name: 'test_plan_analysis',
-    description: 'Analyze test planning status. Threshold: <80% = NO GO, 80-90% = CONDITIONAL, ≥90% = GO.',
+    description: 'Analyze test planning status, optionally scoped to testcase IDs returned by a Zephyr ZQL expression. Threshold: <80% = NO GO, 80-90% = CONDITIONAL, ≥90% = GO.',
     inputSchema: {
       type: 'object',
       properties: {
         projectId: { type: 'number', description: 'Zephyr project ID' },
         releaseId: { type: 'number', description: 'Zephyr release ID' },
+        query: { type: 'string', description: 'Optional Zephyr ZQL expression, e.g. priority = "P1"' },
       },
       required: ['projectId', 'releaseId'],
     },
@@ -142,13 +144,13 @@ const TOOLS = [
   },
   {
     name: 'search_test_cases',
-    description: 'Search test cases by query string.',
+    description: 'Search test cases using a Zephyr ZQL expression, such as priority = "P1".',
     inputSchema: {
       type: 'object',
       properties: {
         projectId: { type: 'number', description: 'Zephyr project ID' },
         releaseId: { type: 'number', description: 'Zephyr release ID' },
-        query: { type: 'string', description: 'Search query string' },
+        query: { type: 'string', description: 'Zephyr ZQL expression, e.g. priority = "P1"' },
         limit: { type: 'number', description: 'Maximum results (default: 50)' },
       },
       required: ['projectId', 'releaseId'],
@@ -264,7 +266,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     
     switch (name) {
       case 'release_readiness':
-        result = await tools.runAllGates(projectId, releaseId);
+        result = await tools.runAllGates(projectId, releaseId, { query: args.query });
         break;
         
       case 'requirement_coverage':
@@ -272,7 +274,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         break;
         
       case 'test_plan_analysis':
-        result = await tools.testPlanAnalysisGate(projectId, releaseId);
+        result = await tools.testPlanAnalysisGate(projectId, releaseId, { query: args.query });
         break;
         
       case 'test_execution':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zephyr-enterprise-tools",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "Comprehensive Zephyr Enterprise Tools - Release Readiness, Project Health, Test Analytics & More",
   "main": "zephyr-enterprise-tools.js",
   "types": "zephyr-enterprise-tools.d.ts",

package/zephyr-enterprise-tools.d.ts

@@ -38,6 +38,11 @@ export interface TestPlanResult extends GateResult {
   assignedTests: number;
 }
 
+export interface TestPlanOptions {
+  /** Optional Zephyr ZQL expression, e.g. `priority = "P1"`. */
+  query?: string;
+}
+
 export interface TestExecutionResult extends GateResult {
   executionPercentage: number;
   completedTests: number;
@@ -65,8 +70,15 @@ export interface ReleaseReadinessResult {
   projectId: number;
   releaseId: number;
   timestamp: string;
+  report: {
+    projectName: string;
+    releaseName: string;
+    generatedAt: string;
+    fileName: string;
+  };
   overallStatus: GateStatus;
   summary: { passed: number; failed: number; conditional: number };
+  details: Record<string, unknown>;
   recommendation: string;
   gates: {
     requirementCoverage: RequirementCoverageResult;
@@ -133,6 +145,7 @@ export interface TestTrendsResult {
 }
 
 export interface SearchTestCasesOptions {
+  /** Zephyr ZQL expression, e.g. `priority = "P1"`. */
   query?: string;
   limit?: number;
 }
@@ -176,10 +189,10 @@ export declare class QualityGates {
 
   // Quality Gates (Release Readiness)
   requirementCoverageGate(projectId: number, releaseId: number): Promise<RequirementCoverageResult>;
-  testPlanAnalysisGate(projectId: number, releaseId: number): Promise<TestPlanResult>;
+  testPlanAnalysisGate(projectId: number, releaseId: number, options?: TestPlanOptions): Promise<TestPlanResult>;
   testExecutionGate(projectId: number, releaseId: number): Promise<TestExecutionResult>;
   defectQualityGate(projectId: number, releaseId: number): Promise<DefectQualityResult>;
-  runAllGates(projectId: number, releaseId: number): Promise<ReleaseReadinessResult>;
+  runAllGates(projectId: number, releaseId: number, options?: TestPlanOptions): Promise<ReleaseReadinessResult>;
 
   // Analytics & Insights
   getProjectHealth(projectId: number, releaseId: number): Promise<ProjectHealthResult>;

package/zephyr-enterprise-tools.js

@@ -113,6 +113,50 @@ export class QualityGates {
     return res.json();
   }
 
+  async POSTv3(path, body) {
+    const v3BaseUrl = this.baseUrl.replace('/latest', '/v3');
+    const res = await fetch(`${v3BaseUrl}${path}`, {
+      method: "POST",
+      headers: { Accept: "application/json", "Content-Type": "application/json", ...this.authHeader() },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Zephyr v3 API ${res.status}: ${text}`);
+    }
+    return res.json();
+  }
+
+  async searchExecutionsByZql(releaseId, query) {
+    const pageSize = 50;
+    let firstResult = 0;
+    const executions = [];
+
+    while (true) {
+      const response = await this.POSTv3("/advancesearch/zql", {
+        firstresult: firstResult,
+        maxresults: pageSize,
+        entitytype: "execution",
+        order: "testcaseId",
+        isascorder: true,
+        is_cfield: false,
+        releaseid: String(releaseId),
+        projectid: "",
+        word: query,
+        zql: true,
+        isOld: false,
+      });
+      const page = response[0]?.results || response.results || [];
+
+      if (!Array.isArray(page) || page.length === 0) break;
+
+      executions.push(...page);
+      firstResult += page.length;
+    }
+
+    return [...new Map(executions.map(execution => [execution.id, execution])).values()];
+  }
+
   async PUT(path, params, body) {
     const url = new URL(`${this.baseUrl}${path}`);
     for (const [k, v] of Object.entries(params)) {
@@ -163,22 +207,36 @@ export class QualityGates {
 
   // ─── Gate 2: Test Plan Analysis ─────────────────────────────────────────────
 
-  async testPlanAnalysisGate(projectId, releaseId) {
-    const summary = await this.GET(`/summary/release/${releaseId}`, { isHideCycleEnabled: false });
-    
-    const totalTestcases = summary.testcase?.totalTestcaseCount || 0;
-    const mappedRequirements = summary.requirement?.mappedRequirementCount || 0;
-    const totalRequirements = summary.requirement?.totalRequirementCount || 0;
-    
-    // Get all executions for the release
-    const executionData = await this.GET("/execution", {
-      releaseid: releaseId,
-      offset: 0,
-      pagesize: 10000,
-      includeanyoneuser: true,
-    });
-    
-    const executions = executionData.results || executionData || [];
+  async testPlanAnalysisGate(projectId, releaseId, options = {}) {
+    const { query } = options;
+    let totalTestcases;
+    let mappedRequirements;
+    let totalRequirements;
+    let executions;
+
+    if (query) {
+      const [matchingTestcases, matchingExecutions] = await Promise.all([
+        this.searchTestCases(projectId, releaseId, {
+          query,
+          limit: Number.MAX_SAFE_INTEGER,
+        }),
+        this.searchExecutionsByZql(releaseId, query),
+      ]);
+      totalTestcases = matchingTestcases.results.length;
+      executions = matchingExecutions;
+    } else {
+      const summary = await this.GET(`/summary/release/${releaseId}`, { isHideCycleEnabled: false });
+      totalTestcases = summary.testcase?.totalTestcaseCount || 0;
+      mappedRequirements = summary.requirement?.mappedRequirementCount || 0;
+      totalRequirements = summary.requirement?.totalRequirementCount || 0;
+      const executionData = await this.GET("/execution", {
+        releaseid: releaseId,
+        offset: 0,
+        pagesize: 10000,
+        includeanyoneuser: true,
+      });
+      executions = executionData.results || executionData || [];
+    }
     const totalExecutions = Array.isArray(executions) ? executions.length : 0;
     
     // Count assigned executions
@@ -223,6 +281,7 @@ export class QualityGates {
       gate: "Test Plan Analysis",
       projectId,
       releaseId,
+      query: query || undefined,
       analysis: {
         testcasePlanning: {
           totalTestcases,
@@ -234,7 +293,7 @@ export class QualityGates {
           assignedExecutions,
           percentage: executionAssignmentPct,
         },
-        requirementCoverage: {
+        requirementCoverage: query ? undefined : {
           totalRequirements,
           mappedRequirements,
           percentage: totalRequirements > 0 ? Math.round((mappedRequirements / totalRequirements) * 100 * 100) / 100 : 0,
@@ -481,13 +540,20 @@ export class QualityGates {
 
   // ─── Run All Gates ──────────────────────────────────────────────────────────
 
-  async runAllGates(projectId, releaseId) {
-    const results = await Promise.all([
-      this.requirementCoverageGate(projectId, releaseId),
-      this.testPlanAnalysisGate(projectId, releaseId),
-      this.testExecutionGate(projectId, releaseId),
-      this.defectQualityGate(projectId, releaseId),
+  async runAllGates(projectId, releaseId, options = {}) {
+    const { query } = options;
+    const [results, project, releases] = await Promise.all([
+      Promise.all([
+        this.requirementCoverageGate(projectId, releaseId),
+        this.testPlanAnalysisGate(projectId, releaseId, { query }),
+        this.testExecutionGate(projectId, releaseId),
+        this.defectQualityGate(projectId, releaseId),
+      ]),
+      this.GET(`/project/${projectId}`).catch(() => ({})),
+      this.GET('/release', { projectid: projectId, isaliasallowed: false }).catch(() => []),
     ]);
+    const release = Array.isArray(releases) ? releases.find(item => Number(item.id) === Number(releaseId)) : undefined;
+    const generatedAt = new Date().toISOString();
     
     const gates = {
       requirementCoverage: results[0],
@@ -517,7 +583,13 @@ export class QualityGates {
     return {
       projectId,
       releaseId,
-      timestamp: new Date().toISOString(),
+      timestamp: generatedAt,
+      report: {
+        projectName: project.name || `Project ${projectId}`,
+        releaseName: release?.name || `Release ${releaseId}`,
+        generatedAt,
+        fileName: this.getReportFileName(project.name || `Project ${projectId}`, release?.name || `Release ${releaseId}`, generatedAt),
+      },
       overallStatus,
       summary: {
         passed: passedGates,
@@ -526,10 +598,72 @@ export class QualityGates {
         total: 4,
       },
       gates,
+      details: this.getReadinessDetails(gates, query),
       recommendation: this.getRecommendation(overallStatus, gates),
     };
   }
 
+  getReportFileName(projectName, releaseName, generatedAt) {
+    const safeSegment = value => String(value)
+      .trim()
+      .replace(/[^a-zA-Z0-9]+/g, '_')
+      .replace(/^_+|_+$/g, '');
+    const timestamp = new Date(generatedAt).toISOString();
+    const date = timestamp.slice(0, 10);
+    const time = timestamp.slice(11, 19).replace(/:/g, '-');
+
+    return `Release_Rediness_${safeSegment(projectName)}_${safeSegment(releaseName)}_${date}_${time}_UTC.pdf`;
+  }
+
+  getReadinessDetails(gates, query) {
+    const plan = gates.testPlanAnalysis;
+    const coverage = gates.requirementCoverage;
+    const execution = gates.testExecution;
+    const defects = gates.defectQuality;
+    const planAnalysis = plan.analysis;
+    const remainingToPlan = Math.max(0, planAnalysis.testcasePlanning.totalTestcases - planAnalysis.testcasePlanning.plannedTestcases);
+    const remainingToExecute = execution.incompleteTests;
+    const additionalTestsForGo = Math.max(0, Math.ceil((0.97 * execution.totalPlannedTests) - execution.completedTests));
+
+    return {
+      testPlanAnalysis: {
+        scope: query ? "ZQL-filtered test cases" : "Release-wide",
+        query: query || undefined,
+        calculation: {
+          testcasePlanning: `${planAnalysis.testcasePlanning.plannedTestcases} / ${planAnalysis.testcasePlanning.totalTestcases} = ${planAnalysis.testcasePlanning.percentage}%`,
+          executionAssignment: `${planAnalysis.executionAssignment.assignedExecutions} / ${planAnalysis.executionAssignment.totalExecutions} = ${planAnalysis.executionAssignment.percentage}%`,
+          overallPlanning: `(${planAnalysis.testcasePlanning.percentage}% + ${planAnalysis.executionAssignment.percentage}%) / 2 = ${plan.overallPlanningPercentage}%`,
+        },
+        actionItems: remainingToPlan > 0
+          ? [`Plan the remaining ${remainingToPlan} test cases.`, "Maintain execution assignment as tests are planned."]
+          : ["Maintain complete test planning and execution assignment."],
+      },
+      requirementCoverage: {
+        scope: "Release-wide",
+        calculation: `${coverage.coveredRequirements} / ${coverage.totalRequirements} = ${coverage.coveragePercentage}%`,
+        uncoveredRequirementIds: [],
+        detailAvailability: "Zephyr release summaries provide the uncovered count but not requirement IDs.",
+        actionItems: coverage.notCoveredRequirements > 0
+          ? [`Create and map tests for ${coverage.notCoveredRequirements} uncovered requirements.`, "Confirm requirement mappings before release sign-off."]
+          : ["Maintain requirement-to-test traceability through release sign-off."],
+      },
+      testExecution: {
+        scope: "Release-wide",
+        calculation: `${execution.completedTests} / ${execution.totalPlannedTests} = ${execution.executionPercentage}%`,
+        actionItems: remainingToExecute > 0
+          ? [`Execute or resolve ${remainingToExecute} incomplete tests.`, `Complete at least ${additionalTestsForGo} additional tests to reach the 97% GO threshold.`, ...(execution.breakdown.failed > 0 ? [`Investigate and rerun ${execution.breakdown.failed} failed test(s).`] : [])]
+          : ["Maintain execution completion through release sign-off."],
+      },
+      defectQuality: {
+        scope: "Release-wide",
+        defects: defects.breakdown,
+        actionItems: defects.unresolvedDefects > 0
+          ? ["Resolve all blocker defects.", "Reduce unresolved high-risk defects to 10 or fewer before approval."]
+          : ["Verify resolved defect fixes with targeted regression coverage.", "Confirm product-owner approval for any Won't Fix resolutions."],
+      },
+    };
+  }
+
   getRecommendation(status, gates) {
     const issues = [];
     
@@ -1031,53 +1165,65 @@ export class QualityGates {
   async searchTestCases(projectId, releaseId, options = {}) {
     const { query = '', status, priority, limit = 50 } = options;
     
-    // Get test cases
-    const params = {
-      projectId: projectId,
-      releaseId: releaseId,
-      offset: 0,
-      maxRecords: 500,
-    };
-    
-    if (query) params.word = query;
-    
     let testcases = [];
-    try {
-      const tcData = await this.GET("/testcase/tree", params);
-      testcases = tcData.results || tcData || [];
-      
-      // Flatten tree structure if needed
-      if (!Array.isArray(testcases)) {
-        testcases = this.flattenTestcaseTree(tcData);
+    if (query) {
+      const pageSize = 5000;
+      let firstResult = 0;
+
+      while (true) {
+        const tcData = await this.POSTv3("/advancesearch/zql", {
+          firstresult: firstResult,
+          maxresults: pageSize,
+          entitytype: "testcase",
+          order: "orderId",
+          isascorder: true,
+          is_cfield: false,
+          releaseid: String(releaseId),
+          projectid: String(projectId),
+          word: query,
+          zql: true,
+          isOld: false,
+        });
+        const page = tcData[0]?.results || tcData.results || [];
+
+        if (!Array.isArray(page) || page.length === 0) break;
+
+        testcases.push(...page);
+        firstResult += page.length;
       }
-    } catch (e) {
-      // Try alternative endpoint
+      testcases = [...new Map(testcases.map(testcase => [testcase.testcase?.id || testcase.id, testcase])).values()];
+    } else {
+      const params = {
+        projectId,
+        releaseId,
+        offset: 0,
+        maxRecords: 500,
+      };
       try {
-        const tcData = await this.GET("/testcase", params);
+        const tcData = await this.GET("/testcase/tree", params);
         testcases = tcData.results || tcData || [];
-      } catch (e2) {
-        return {
-          tool: "Search Test Cases",
-          projectId,
-          releaseId,
-          error: "Unable to fetch test cases",
-          results: [],
-        };
+        if (!Array.isArray(testcases)) {
+          testcases = this.flattenTestcaseTree(tcData);
+        }
+      } catch (e) {
+        try {
+          const tcData = await this.GET("/testcase", params);
+          testcases = tcData.results || tcData || [];
+        } catch (e2) {
+          return {
+            tool: "Search Test Cases",
+            projectId,
+            releaseId,
+            error: "Unable to fetch test cases",
+            results: [],
+          };
+        }
       }
     }
     
     // Filter results
     let filtered = testcases;
     
-    if (query) {
-      const q = query.toLowerCase();
-      filtered = filtered.filter(tc => 
-        (tc.name || '').toLowerCase().includes(q) ||
-        (tc.testcaseKey || tc.alternateId || '').toLowerCase().includes(q) ||
-        (tc.description || '').toLowerCase().includes(q)
-      );
-    }
-    
     if (status) {
       filtered = filtered.filter(tc => 
         (tc.status || '').toLowerCase() === status.toLowerCase()
@@ -1091,17 +1237,20 @@ export class QualityGates {
     }
     
     // Map to clean output
-    const results = filtered.slice(0, limit).map(tc => ({
-      id: tc.id,
-      key: tc.testcaseKey || tc.alternateId,
-      name: tc.name,
-      status: tc.status,
-      priority: tc.priority,
-      automated: tc.automated || tc.isAutomated || false,
+    const results = filtered.slice(0, limit).map(tc => {
+      const testcase = tc.testcase || tc;
+      return {
+      id: testcase.id,
+      key: testcase.testcaseKey || testcase.alternateId || testcase.externalId,
+      name: testcase.name,
+      status: testcase.status,
+      priority: testcase.priority,
+      automated: testcase.automated || testcase.isAutomated || false,
       folder: tc.folderPath || tc.tcrCatalogTreeId?.name,
-      estimatedTime: tc.estimatedTime,
-      tags: tc.tags || [],
-    }));
+      estimatedTime: testcase.estimatedTime,
+      tags: testcase.tags || [],
+      };
+    });
     
     return {
       tool: "Search Test Cases",