devops-plugin-kit 0.1.0

package/@danieli-automation/devops-plugin-features/src/features/work-items/utils/filter.ts

@@ -0,0 +1,189 @@
+import FieldConstant from "features/work-items/constants/FieldConstant";
+import StateConstant from "features/work-items/constants/StateConstant";
+import TypeConstant from "features/work-items/constants/TypeConstant";
+import { AdoWorkItemType } from "features/work-items/types/AdoWorkItemType";
+
+/**
+ * Filters work items to include only Epics.
+ * 
+ * @param workItems Array of work items to filter.
+ * @returns Filtered array containing only Epics.
+ * 
+ */
+export function filterEpics(workItems: AdoWorkItemType[]) {
+    return workItems.filter(
+        wi => wi.fields[FieldConstant.WORK_ITEM_FIELD_WORK_ITEM_TYPE] === TypeConstant.EPIC_TYPE
+    );
+}
+
+/**
+ * Filters work items to include only Features.
+ * 
+ * @param workItems Array of work items to filter.
+ * @returns Filtered array containing only Features.
+ */
+export function filterFeatures(workItems: AdoWorkItemType[]) {
+    return workItems.filter(
+        wi => wi.fields[FieldConstant.WORK_ITEM_FIELD_WORK_ITEM_TYPE] === TypeConstant.FEATURE_TYPE
+    );
+}
+
+/**
+ * Filters work items to include only Product Backlog Items (PBIs) and Bugs.
+ * 
+ * @param workItems Array of work items to filter.
+ * @returns Filtered array containing only PBIs and Bugs.
+ * 
+ */
+export function filterPbisAndBugs(workItems: AdoWorkItemType[]) {
+    return workItems.filter((workItem: AdoWorkItemType) => {
+        const workItemType = workItem.fields[FieldConstant.WORK_ITEM_FIELD_WORK_ITEM_TYPE];
+        return workItemType === TypeConstant.PRODUCT_BACKLOG_ITEM_TYPE || workItemType === TypeConstant.BUG_TYPE;
+    });
+};
+
+/**
+ * Filters work items to include only Tasks that are not in the Removed state.
+ * 
+ * @param workItems Array of work items to filter.
+ * @returns Filtered array containing only Tasks that are not removed.
+ * 
+ */
+export function filterTasks(workItems: AdoWorkItemType[]) {
+    return workItems.filter((workItem: AdoWorkItemType) => {
+        const workItemType = workItem.fields[FieldConstant.WORK_ITEM_FIELD_WORK_ITEM_TYPE];
+        const isRemoved = workItem.fields[FieldConstant.WORK_ITEM_FIELD_STATE] === StateConstant.REMOVED_STATE;
+        return workItemType === TypeConstant.TASK_TYPE && !isRemoved;
+    });
+};
+
+/** 
+ * @description: Filters child work items
+ * @param childrenWorkItems: Array of child work items to filter.
+ * @param selectedAssignedTo: An array of selected assignee unique names.
+ * @param parentId: The parent work item ID to filter by.
+ * @return: Filtered array of child work items.
+*/
+export function filterChildrenWorkItemsByParentId(childrenWorkItems: AdoWorkItemType[], parentId: number, selectedAssignedTo?: string[]) {
+    return childrenWorkItems.filter((t: AdoWorkItemType) => {
+        if (!t) return false;
+
+        if (t.fields[FieldConstant.WORK_ITEM_FIELD_STATE] == StateConstant.REMOVED_STATE) return false;
+
+        const viaRelations = t.relations?.some(
+            (rel: any) => rel.rel === "System.LinkTypes.Hierarchy-Reverse" && rel.url.endsWith(`/${parentId}`)
+        );
+
+        const viaParentField = t.fields?.[FieldConstant.WORK_ITEM_FIELD_PARENT] === parentId;
+
+        if (!selectedAssignedTo || selectedAssignedTo.length === 0) {
+            return !!(viaRelations || viaParentField);
+        }
+
+        let isAssigneeMatched = filterWorkItemsByAssignee(t, selectedAssignedTo);
+
+        if (t._children && t._children.length > 0) {
+            for (const child of t._children) {
+                if (filterWorkItemsByAssignee(child, selectedAssignedTo)) {
+                    isAssigneeMatched = true;
+                    break;
+                }
+            }
+            if (!isAssigneeMatched) return false;
+        }
+
+        if (!isAssigneeMatched) return false;
+
+        return !!(viaRelations || viaParentField);
+    });
+}
+
+/** 
+* @description: Filters a work item based on selected assignees.
+* @param workItem: The work item to filter.
+* @param selectedAssignedTo: An array of selected assignee unique names.
+* @return: True if the work item matches the selected assignees, false otherwise.
+*/
+export function filterWorkItemsByAssignee(workItem: AdoWorkItemType, selectedAssignedTo: string[]) {
+    if (!selectedAssignedTo?.length) return true;
+
+    const assigned = workItem.fields?.[FieldConstant.WORK_ITEM_FIELD_ASSIGNED_TO] as any | undefined;
+    const uniqueName = assigned?.uniqueName as string | undefined;
+
+    const hasUnassigned = selectedAssignedTo.includes("__unassigned__");
+    const selectedReal = selectedAssignedTo.filter(x => x !== "__unassigned__");
+
+    const isUnassigned = !uniqueName;
+
+    const matchesReal = selectedReal.length > 0
+        ? (!!uniqueName && selectedReal.includes(uniqueName))
+        : false;
+
+    const matchesUnassigned = hasUnassigned && isUnassigned;
+
+    if (selectedReal.length === 0 && hasUnassigned) return matchesUnassigned;
+    if (selectedReal.length > 0 && !hasUnassigned) return matchesReal;
+    return matchesReal || matchesUnassigned;
+}
+
+
+/**
+ * @description: Checks if a work item matches a given keyword across defined fields.
+ * @param workItem   The work item to check.
+ * @param keyword The keyword to match against the work item's specific fields.
+ * @returns True if the keyword matches any field in the work item that is specified before, false otherwise.
+ */
+export function filterWorkItemsByKeyword(workItem: AdoWorkItemType, keyword: string): boolean {
+    const kw = keyword.trim().toLowerCase();
+    if (!kw) return true;
+
+    const fields = workItem.fields ?? {};
+
+    for (const field of [
+        FieldConstant.WORK_ITEM_FIELD_ID,
+        FieldConstant.WORK_ITEM_FIELD_TITLE,
+        FieldConstant.WORK_ITEM_FIELD_TAGS,
+        FieldConstant.WORK_ITEM_FIELD_AREA_PATH,
+        FieldConstant.WORK_ITEM_FIELD_ITERATION_PATH
+    ]) {
+        const value = fields[field];
+
+        if (!value) continue;
+
+        //for Id like fields
+        if (typeof value === "number") {
+            if (String(value) === kw) return true;
+            continue;
+        }
+
+        // for title like fields
+        if (typeof value === "string") {
+            if (value.toLowerCase().includes(kw)) return true;
+            continue;
+        }
+
+        //for area path and tags like fields
+        if (Array.isArray(value)) {
+            if (value.some(v => String(v).toLowerCase().includes(kw))) return true;
+            continue;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * @description: Checks whether a work item contains at least one of the selected tags.
+ *                Tags are read from the work item's tag field, split by semicolon (;),
+ *                trimmed, and compared against the provided tag list.
+ * @param workItem     The work item whose tags will be evaluated.
+ * @param selectedTags The list of tags to match against the work item's tags.
+ * @returns True if the work item contains at least one of the selected tags, false otherwise.
+ */
+export function filterWorkItemsByTags(workItem: AdoWorkItemType, selectedTags: string[]) {
+    const tagsStr = String(workItem.fields[FieldConstant.WORK_ITEM_FIELD_TAGS] ?? "");
+    const tags = tagsStr.split(";").map(t => t.trim()).filter(Boolean);
+    const tagSet = new Set(tags);
+    const someTagsExists = selectedTags.some(t => tagSet.has(t));
+    return someTagsExists
+}

package/@danieli-automation/devops-plugin-features/src/features/work-items/utils/workItem.ts

@@ -0,0 +1,245 @@
+import { TeamMember } from "features/teams/types/TeamMemberType";
+import FieldConstant from "features/work-items/constants/FieldConstant";
+import TypeConstant from "features/work-items/constants/TypeConstant";
+import { AdoWorkItemType } from "features/work-items/types/AdoWorkItemType";
+import { filterEpics, filterFeatures } from "./filter.js";
+
+/**
+ * Get the Epic work item that is the ancestor of the given work item.
+ * 
+ * @param workItem The work item for which to find the Epic ancestor.
+ * @param workItems The list of all work items to search within.
+ * @returns The Epic work item if found, otherwise undefined.
+ * 
+ */
+export function getEpicByWorkItem(workItem: AdoWorkItemType, workItems: AdoWorkItemType[]): AdoWorkItemType | undefined {
+    const epics = filterEpics(workItems);
+    const features = filterFeatures(workItems);
+
+    const hasChild = (parent: AdoWorkItemType, childId: number) => {
+        const relations = parent.relations || [];
+        return relations.some(rel => {
+            if (rel.rel !== "System.LinkTypes.Hierarchy-Forward") return false;
+            const match = rel.url && rel.url.match(/(\d+)$/);
+            const parsedId = match ? Number(match[1]) : null;
+            return parsedId === childId;
+        });
+    };
+
+    //find the feature that is (direct) parent of current item
+    let parentFeature: AdoWorkItemType | undefined;
+
+    if (workItem.fields[FieldConstant.WORK_ITEM_FIELD_WORK_ITEM_TYPE] === TypeConstant.FEATURE_TYPE) {
+        parentFeature = workItem;
+    } else {
+        parentFeature = features.find(f => hasChild(f, workItem.id));
+    }
+
+    if (!parentFeature) {
+        return undefined;
+    }
+
+    return epics.find(e => hasChild(e, parentFeature!.id));
+}
+
+/**
+ * Builds a lookup map from Feature ID -> Epic metadata (id + title),
+ * by scanning Epic work items and their forward hierarchy child links.
+ * 
+ * @param topLevelParentWorkItems A list of top-level parent work items (typically epics/features).
+ * @returns A map where the key is featureId and the value contains epicId and epicTitle.
+ * 
+ */
+export function getEpicByFeatureId(topLevelParentWorkItems: AdoWorkItemType[]) {
+    const map = new Map<number, { epicId: number; epicTitle: string }>();
+
+    for (const wi of topLevelParentWorkItems) {
+        const type = String(wi.fields[FieldConstant.WORK_ITEM_FIELD_WORK_ITEM_TYPE] || "");
+        if (type.toLowerCase() !== "epic") continue;
+
+        const epicId = wi.id;
+        const epicTitle = String(wi.fields[FieldConstant.WORK_ITEM_FIELD_TITLE] || "");
+
+        for (const featureId of getChildWorkItemIdsFromRelations(wi)) {
+            map.set(featureId, { epicId, epicTitle });
+        }
+    }
+    return map;
+}
+
+
+/**
+ * Get the Feature work item that is the parent of the given work item.
+ * 
+ * @param workItem The work item for which to find the Feature parent.
+ * @param workItems The list of all work items to search within.
+ * @returns The Feature work item if found, otherwise undefined.
+ * 
+ */
+export function getFeatureByWorkItem(workItem: AdoWorkItemType, workItems: AdoWorkItemType[]): AdoWorkItemType | undefined {
+    const features = filterFeatures(workItems);
+
+    return features?.find(f => {
+        const relations = f.relations || [];
+        return relations.some(rel => {
+            const childRel = rel.rel === "System.LinkTypes.Hierarchy-Forward";
+            const match = rel.url && rel.url.match(/(\d+)$/);
+            const childId = match ? Number(match[1]) : null;
+            return childRel && childId === workItem.id;
+        });
+    });
+}
+
+
+/**
+ * Builds a lookup map from Work Item ID -> Feature metadata (id + title),
+ * by scanning Feature work items and their forward hierarchy child links.
+ * 
+ * @param topLevelParentWorkItems A list of top-level parent work items (typically features).
+ * @returns A map where the key is child workItemId and the value contains featureId and featureTitle.
+ * 
+ */
+export function getFeatureByWorkItemId(topLevelParentWorkItems: AdoWorkItemType[]) {
+    const map = new Map<number, { featureId: number; featureTitle: string }>();
+
+    for (const feature of topLevelParentWorkItems) {
+        const type = String(feature.fields[FieldConstant.WORK_ITEM_FIELD_WORK_ITEM_TYPE] || "");
+        if (type.toLowerCase() !== "feature") continue;
+
+        const featureId = feature.id;
+        const featureTitle = String(feature.fields[FieldConstant.WORK_ITEM_FIELD_TITLE] || "");
+
+        for (const childId of getChildWorkItemIdsFromRelations(feature)) {
+            map.set(childId, { featureId, featureTitle });
+        }
+    }
+
+    return map;
+}
+
+/**
+ * Calculates the total remaining work from an array of work items.
+ * 
+ * @param workItems Array of work items to calculate remaining work from.
+ * @returns Total remaining work as a number.
+ * 
+ */
+export function calculateTotalRemainingWorkByWorkItems(workItems: AdoWorkItemType[]) {
+    return workItems.reduce((total, wi) => total + (Number(wi?.fields[FieldConstant.WORK_ITEM_FIELD_REMAINING_WORK]) || 0), 0);
+}
+
+
+/**
+ * Get the assignee from the given work item
+ * 
+ * @param workItem The work item that is asked to get responsible assignee from
+ * @returns Assignee as Team Member type.
+ */
+export function getAssigneeFromWorkItem(workItem: AdoWorkItemType) {
+    const v = workItem.fields?.[FieldConstant.WORK_ITEM_FIELD_ASSIGNED_TO];
+
+    if (!v || typeof v !== "object") {
+        return { id: "", displayName: "Unassigned", uniqueName: "" } as TeamMember;
+    }
+
+    return v as TeamMember;
+};
+
+/**
+ * Extracts child work item IDs from a work item's relations by reading
+ * forward hierarchy links (System.LinkTypes.Hierarchy-Forward).
+ * 
+ * @param item The work item whose relations will be parsed for child links.
+ * @returns A list of child work item IDs. Returns an empty array if there are no relations.
+ * 
+ */
+export function getChildWorkItemIdsFromRelations(item: AdoWorkItemType): number[] {
+    if (!Array.isArray(item?.relations)) return [];
+
+    return item.relations
+        .filter((r: any) => r.rel === "System.LinkTypes.Hierarchy-Forward")
+        .map((r: any) => Number(r.url.match(/(\d+)$/)?.[1] ?? 0))
+        .filter((id: number) => Number.isFinite(id) && id > 0);
+}
+
+/**
+ * @description: Extracts parent work item IDs from task relations (Hierarchy-Reverse).
+ * @param tasks Array of task work items (must include relations).
+ * @returns Array of unique parent IDs.
+ */
+export function extractParentIdsFromTasks(tasks: AdoWorkItemType[]): number[] {
+    const out = new Set<number>();
+
+    for (const t of tasks) {
+        for (const rel of t.relations ?? []) {
+            if (rel.rel !== "System.LinkTypes.Hierarchy-Reverse") continue;
+            const match = String(rel.url ?? "").match(/(\d+)$/);
+            if (!match) continue;
+            const id = Number(match[1]);
+            if (!Number.isNaN(id)) out.add(id);
+        }
+    }
+
+    return Array.from(out);
+}
+
+/**
+ * Checks whether a work item should be treated as a Task by comparing its
+ * work item type field against the Task type constant.
+ * 
+ * @param item The work item to check.
+ * @returns True if the work item type matches Task, otherwise false.
+ * 
+ */
+export function isTask(item: AdoWorkItemType) {
+    return String(item?.fields?.[FieldConstant.WORK_ITEM_FIELD_WORK_ITEM_TYPE]).toLowerCase() === TypeConstant.TASK_TYPE.toLowerCase();
+}
+
+/**
+ * Parses and returns the tags of a work item as a cleaned string array.
+ * Azure DevOps stores tags as a semicolon-separated string.
+ * 
+ * @param workItem The work item to extract tags from.
+ * @returns A trimmed, non-empty list of tags.
+ * 
+ */
+export function getTagsByWorkItem(workItem: AdoWorkItemType) {
+    const tags = (workItem.fields[FieldConstant.WORK_ITEM_FIELD_TAGS] || "").split(";");
+    const validatedTags = tags.map((tag: string) => tag.trim());
+    const filteredTags = validatedTags.filter((tag: string) => tag);
+    return filteredTags;
+}
+
+/**
+ * Returns the IDs of work items that can be expanded (i.e., non-task items that have at least one child).
+ * Typically used to determine which parent rows should show an expand/collapse control in the UI.
+ *
+ * Rules:
+ * - Excludes items of type "Task" (tasks are usually the leaf-level items).
+ * - Includes only items that have at least one child relation.
+ *
+ * @param workItems The list of work items to evaluate.
+ * @returns A list of work item IDs that are expandable.
+ */
+export function getExpandableWorkItemIds(workItems: AdoWorkItemType[]) {
+    return workItems
+        .filter((w) => String(w.fields?.[FieldConstant.WORK_ITEM_FIELD_WORK_ITEM_TYPE] || "").toLowerCase() !== TypeConstant.TASK_TYPE.toLowerCase())
+        .filter((w) => getChildWorkItemIdsFromRelations(w).length > 0)
+        .map((w) => w.id);
+}
+
+/**
+ * Find a task by its ID across multiple buckets. (e.g., newTasks, existingTasks, deletedTasks)
+ * 
+ * @param did 
+ * @param buckets 
+ * @returns The found task or null if not found.
+ */
+export function findTaskById(did: string, ...buckets: any[][]) {
+    const [, , raw] = did.split(":");
+    for (const b of buckets) {
+        const t = b.find(x => String(x.id ?? x.tempId) === raw);
+        if (t) return t;
+    }
+    return null;
+};

package/@danieli-automation/devops-plugin-features/src/test/mocks/azure-devops-extension-api/Work.ts

@@ -0,0 +1,5 @@
+export enum TimeFrame {
+  Past = 0,
+  Current = 1,
+  Future = 2
+}

package/@danieli-automation/devops-plugin-features/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "noImplicitAny": false,
+    "baseUrl": ".",
+    "paths": {
+      "features/*": ["src/features/*"],
+      "core/*": ["src/core/*"],
+      "app/*": ["src/app/*"],
+      "src/*": ["src/*"]
+    }
+  },
+  "include": ["src"]
+}

package/@danieli-automation/devops-plugin-features/vitest.config.ts

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  resolve: {
+    alias: [
+      {
+        find: "azure-devops-extension-api/Work",
+        replacement: path.resolve(__dirname, "src/test/mocks/azure-devops-extension-api/Work.ts")
+      },
+      { find: /^features\/(.*)$/, replacement: path.resolve(__dirname, "src/features/$1") },
+      { find: /^core\/(.*)$/, replacement: path.resolve(__dirname, "src/core/$1") },
+      { find: /^app\/(.*)$/, replacement: path.resolve(__dirname, "src/app/$1") },
+      { find: /^src\/(.*)$/, replacement: path.resolve(__dirname, "src/$1") }
+    ]
+  },
+  test: {
+    environment: "node",
+    globals: true
+  }
+});

package/README.md

@@ -0,0 +1,55 @@
+# devops-plugin-kit
+
+Monorepo for reusable Azure DevOps plugin packages.
+
+## Packages
+
+- `@danieli-automation/devops-plugin-features`: shared feature-level state, hooks, and helpers
+- `@danieli-automation/devops-plugin-core`: core plugin utilities and API wrappers
+- `@danieli-automation/create-devops-plugin`: template/bootstrap utility
+
+## Development
+
+```bash
+npm install
+npm run build
+```
+
+## Create DevOps Plugin
+
+Run from this monorepo workspace:
+
+```bash
+npm run build --workspace @danieli-automation/create-devops-plugin
+npx create-devops-plugin CapacityPlanner --publisher danieli-automation --target-dir ./generated --extension-id capacity-planner --no-install --force
+```
+
+Install and use in another project:
+
+```bash
+npm i -D @danieli-automation/create-devops-plugin
+npx create-devops-plugin MyPlugin --publisher danieli-automation --target-dir ./plugins
+```
+
+`npm create` style (after publish):
+
+```bash
+npm create @danieli-automation/devops-plugin -- MyPlugin --publisher danieli-automation --target-dir ./plugins
+```
+
+Example parameters for `createPluginTemplate(...)`:
+
+- `targetDir`: parent folder where the plugin folder will be created
+- `pluginName`: project/plugin folder name and display name
+- `publisher`: Azure DevOps publisher id
+- `extensionId` (optional): manifest id (defaults from `pluginName`)
+- `installDependencies` (optional): runs `npm install` in generated plugin (default `true`)
+- `force` (optional): allows writing into non-empty target folder (default `false`)
+
+## Publish
+
+```bash
+npm publish --workspace @danieli-automation/devops-plugin-features
+npm publish --workspace @danieli-automation/devops-plugin-core
+npm publish --workspace @danieli-automation/create-devops-plugin
+```

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "devops-plugin-kit",
+  "private": false,
+  "version": "0.1.0",
+  "description": "Shared toolkit for Azure DevOps plugins",
+  "author": "Danieli Automation",
+  "license": "MIT",
+  "type": "module",
+  "workspaces": [
+    "@danieli-automation/*"
+  ],
+  "scripts": {
+    "build": "npm run -ws build",
+    "clean": "npm run -ws clean",
+    "lint": "npm run -ws lint",
+    "test": "npm run -ws test"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^4.40.0",
+    "@types/node": "^24.3.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "azure-devops-extension-api": "^4.251.0",
+    "azure-devops-extension-sdk": "^4.0.2",
+    "react-query": "^3.39.3",
+    "typescript": "^5.9.2",
+    "zustand": "4.5.7"
+  }
+}

package/tsconfig.base.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  }
+}