@mcp-consultant-tools/azure-devops 30.0.0-beta.16 → 30.0.0-beta.18

package/build/sync/markdown-serializer.d.ts

@@ -2,7 +2,22 @@
  * Markdown Serialization Utilities
  *
  * Convert between ADO work items and local markdown files.
- * Uses YAML frontmatter for metadata and markdown sections for content.
+ *
+ * Files use YAML frontmatter (scalar fields — ADO refnames or friendly
+ * aliases) + body sections (long text fields tagged with
+ * `<!-- ado-field: REFNAME -->` comments). The sync engine is generic:
+ * any field named in the file is pushed to ADO, any field not named is
+ * left alone.
+ *
+ * Legacy files (pre-annotation) are detected and parsed via a
+ * legacy-mappings fallback table. They auto-upgrade to the annotated
+ * format on the next pull.
+ */
+import { type LocalOnlySection } from './annotation-parser.js';
+/**
+ * Subset of frontmatter values used by downstream services (sync-service,
+ * file-utils) via stable friendly names. Always populated on parse by
+ * pulling the corresponding refname out of `fieldMap`.
  */
 export interface WorkItemFrontmatter {
     id: number;
@@ -20,6 +35,11 @@ export interface WorkItemFrontmatter {
     lastSyncedRevision: number;
     lastSyncedAt: string;
 }
+/**
+ * Legacy slot for the four historically-supported custom fields. Retained
+ * so that pre-annotation callers (and reports) keep working. New-style
+ * consumers should read `bodyFieldMap` instead.
+ */
 export interface AdditionalFields {
     howToTest?: string;
     deploymentInformation?: string;
@@ -27,13 +47,23 @@ export interface AdditionalFields {
     postdeploymentSteps?: string;
 }
 export interface ParsedWorkItemFile {
+    /** Friendly-name frontmatter view for back-compat. */
     frontmatter: WorkItemFrontmatter;
+    /** All scalar ADO fields from frontmatter, keyed by refname. */
+    fieldMap: Record<string, FieldValue>;
+    /** All body text fields (from annotated sections OR legacy headings), keyed by refname. */
+    bodyFieldMap: Record<string, string>;
+    /** Sections with no ADO-field annotation — preserved in the file but not pushed. */
+    localOnlySections: LocalOnlySection[];
+    /** Work item type (mirrors frontmatter.type). */
+    workItemType: string;
     description: string;
     reproSteps: string;
     acceptanceCriteria: string;
     additionalFields: AdditionalFields;
     rawContent: string;
 }
+export type FieldValue = string | number | boolean | string[];
 export interface CommentsFrontmatter {
     id: number;
     title: string;
@@ -45,50 +75,25 @@ export interface ParsedComment {
     date: string;
     content: string;
 }
-/**
- * Result of converting work item to markdown
- */
 export interface WorkItemToMarkdownResult {
     content: string;
     skippedFields: string[];
 }
 /**
- * Convert an ADO work item to markdown file content
+ * Serialize an ADO work item to an annotated markdown file.
  *
- * @param workItem - The work item from ADO API
- * @param revision - The revision number
- * @returns Object with markdown content and list of skipped fields (if any were HTML)
+ * Follows the template for `fields['System.WorkItemType']`. Frontmatter
+ * order and body-section order come from the template. Fields the ADO
+ * response carries but the template doesn't mention are appended to the
+ * frontmatter with a discovery comment (see D4 in the design plan).
  */
 export declare function workItemToMarkdown(workItem: any, revision: number): WorkItemToMarkdownResult;
-/**
- * Parse a markdown file to extract frontmatter and content sections
- */
 export declare function parseWorkItemMarkdown(content: string): ParsedWorkItemFile;
-/**
- * Convert ADO comments to a read-only markdown file
- */
-export declare function commentsToMarkdown(workItem: any, comments: any[]): string;
-/**
- * Build ADO patch operations from parsed markdown changes
- * Only updates fields that have actually changed.
- * Auto-converts HTML fields to markdown format unless skipAutoConvert is true.
- *
- * @param parsed - Parsed work item file
- * @param currentWorkItem - Current work item from ADO
- * @param skipAutoConvert - Skip automatic HTML-to-markdown conversion (default: false)
- */
 export declare function buildPatchOperations(parsed: ParsedWorkItemFile, currentWorkItem: any, skipAutoConvert?: boolean): {
     operations: any[];
     skippedFields: string[];
     convertedFields: string[];
 };
-/**
- * Update the lastSyncedRevision in a markdown file content
- */
-export declare function updateSyncRevision(content: string, newRevision: number): string;
-/**
- * Frontmatter for new work items (before they have an ID)
- */
 export interface NewWorkItemFrontmatter {
     title: string;
     type: string;
@@ -101,53 +106,40 @@ export interface NewWorkItemFrontmatter {
     areaPath?: string;
     iterationPath?: string;
 }
-/**
- * Parsed new work item file structure
- */
 export interface ParsedNewWorkItemFile {
     frontmatter: NewWorkItemFrontmatter;
+    fieldMap: Record<string, FieldValue>;
+    bodyFieldMap: Record<string, string>;
+    localOnlySections: LocalOnlySection[];
+    workItemType: string;
     description: string;
     reproSteps: string;
     acceptanceCriteria: string;
     additionalFields: AdditionalFields;
     rawContent: string;
 }
-/**
- * Check if a work item frontmatter indicates a new (not yet created) work item
- * New work items don't have an 'id' field
- */
 export declare function isNewWorkItem(frontmatter: Record<string, any>): boolean;
-/**
- * Parse a markdown file for a NEW work item (no id required)
- */
 export declare function parseNewWorkItemMarkdown(content: string): ParsedNewWorkItemFile;
 /**
- * Result of building new work item fields, split into standard and custom.
- * Custom fields (MoSCoW, HowToTest, Deployment fields) cannot be set during
- * ADO work item creation — they must be set via a follow-up update.
+ * Split new-work-item fields into standard (safe for creation) and custom
+ * (must be set via a follow-up update because ADO rejects custom fields
+ * during creation).
+ *
+ * Standard = refname starts with `System.*` or `Microsoft.VSTS.*`.
+ * Custom   = everything else (conventionally `Custom.*`).
  */
 export interface NewWorkItemFieldSplit {
-    /** Standard ADO fields safe for creation */
     standardFields: Record<string, any>;
-    /** Custom fields that must be set via update after creation */
     customFields: Record<string, any>;
 }
-/**
- * Build ADO fields object for creating a new work item
- * Inherits areaPath and iterationPath from parent work item when available
- *
- * Returns fields split into standard (safe for creation) and custom (require
- * a follow-up update) because ADO rejects custom fields during work item creation.
- */
 export declare function buildNewWorkItemFields(parsed: ParsedNewWorkItemFile, parentWorkItem?: any): NewWorkItemFieldSplit;
-/**
- * Generate a new work item template markdown file
- * When parentId is undefined, creates a standalone work item template
- */
 export declare function generateNewWorkItemTemplate(parentId: number | undefined, parentTitle: string, project: string, workItemType?: string): string;
+export declare function commentsToMarkdown(workItem: any, comments: any[]): string;
+export declare function updateSyncRevision(content: string, newRevision: number): string;
+export declare function convertNewFileToSynced(content: string, workItemId: number, revision: number, url: string): string;
 /**
- * Update a new work item file after creation with the assigned ID
- * Converts it from a "new" file to a synced file with proper frontmatter
+ * Return the list of large-text (body) refnames that should be HTML-checked
+ * for a given work-item type. Driven by the loaded template.
  */
-export declare function convertNewFileToSynced(content: string, workItemId: number, revision: number, url: string): string;
+export declare function templateBodyRefnamesForType(workItemType: string): string[];
 //# sourceMappingURL=markdown-serializer.d.ts.map

package/build/sync/markdown-serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-serializer.d.ts","sourceRoot":"","sources":["../../src/sync/markdown-serializer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"markdown-serializer.d.ts","sourceRoot":"","sources":["../../src/sync/markdown-serializer.ts"],"names":[],"mappings":"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"}