@mcoda/core 0.1.8 → 0.1.11

package/dist/services/docs/review/gates/TerminologyNormalizationGate.js

@@ -0,0 +1,217 @@
+import { promises as fs } from "node:fs";
+import { loadGlossary } from "../Glossary.js";
+const CONTRADICTION_GROUPS = [
+    {
+        id: "token_identity",
+        label: "Anonymous vs identified token terminology",
+        keys: ["anonymous_token", "identified_token"],
+    },
+];
+const SEVERITY_ALIAS = "medium";
+const SEVERITY_CONTRADICTION = "blocker";
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const buildPattern = (term) => new RegExp(`\\b${escapeRegExp(term)}\\b`, "i");
+const buildStripper = (pattern) => new RegExp(pattern.source, "gi");
+const isFenceLine = (line) => /^```|^~~~/.test(line.trim());
+const isExampleHeading = (heading) => /example|sample/i.test(heading);
+const buildPatterns = (glossary) => {
+    return glossary.entries.map((entry) => {
+        const canonical = buildPattern(entry.term);
+        const aliases = (entry.aliases ?? []).map((alias) => ({
+            alias,
+            pattern: buildPattern(alias),
+        }));
+        return {
+            key: entry.key,
+            term: entry.term,
+            canonical,
+            canonicalStripper: buildStripper(canonical),
+            aliases,
+        };
+    });
+};
+const buildAliasIssue = (input) => {
+    const message = `Non-canonical term "${input.alias}" detected; use "${input.canonical}".`;
+    return {
+        id: `gate-terminology-normalization-${input.record.kind}-${input.key}-${input.lineNumber}`,
+        gateId: "gate-terminology-normalization",
+        severity: SEVERITY_ALIAS,
+        category: "terminology",
+        artifact: input.record.kind,
+        message,
+        remediation: `Replace "${input.alias}" with the canonical term "${input.canonical}".`,
+        location: {
+            kind: "line_range",
+            path: input.record.path,
+            lineStart: input.lineNumber,
+            lineEnd: input.lineNumber,
+            excerpt: input.alias,
+        },
+        metadata: {
+            entryKey: input.key,
+            canonicalTerm: input.canonical,
+            alias: input.alias,
+            heading: input.heading,
+        },
+    };
+};
+const buildContradictionIssue = (input) => {
+    const termList = input.terms.join(" vs ");
+    return {
+        id: `gate-terminology-normalization-contradiction-${input.lineNumber}`,
+        gateId: "gate-terminology-normalization",
+        severity: SEVERITY_CONTRADICTION,
+        category: "terminology",
+        artifact: input.record.kind,
+        message: `Conflicting canonical terminology detected (${termList}).`,
+        remediation: `Select one canonical term or explicitly define how both apply. (${input.label})`,
+        location: {
+            kind: "line_range",
+            path: input.record.path,
+            lineStart: input.lineNumber,
+            lineEnd: input.lineNumber,
+            excerpt: termList,
+        },
+        metadata: {
+            issueType: "contradiction",
+            conflictKeys: input.keys,
+            conflictTerms: input.terms,
+            label: input.label,
+        },
+    };
+};
+const scanRecord = async (record, patterns) => {
+    const issues = [];
+    const canonicalHits = [];
+    const notes = [];
+    try {
+        const content = await fs.readFile(record.path, "utf8");
+        const lines = content.split(/\r?\n/);
+        let inFence = false;
+        let allowSection = false;
+        let currentHeading;
+        for (let i = 0; i < lines.length; i += 1) {
+            const line = lines[i] ?? "";
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            if (isFenceLine(trimmed)) {
+                inFence = !inFence;
+                continue;
+            }
+            const headingMatch = trimmed.match(/^#{1,6}\s+(.*)$/);
+            if (headingMatch) {
+                currentHeading = headingMatch[1]?.trim() || undefined;
+                allowSection = currentHeading ? isExampleHeading(currentHeading) : false;
+            }
+            if (inFence || allowSection)
+                continue;
+            for (const pattern of patterns) {
+                if (pattern.canonical.test(line)) {
+                    canonicalHits.push({
+                        key: pattern.key,
+                        term: pattern.term,
+                        record,
+                        lineNumber: i + 1,
+                        heading: currentHeading,
+                    });
+                }
+                if (pattern.aliases.length === 0)
+                    continue;
+                const lineWithoutCanonical = line.replace(pattern.canonicalStripper, "");
+                for (const alias of pattern.aliases) {
+                    if (!alias.pattern.test(lineWithoutCanonical))
+                        continue;
+                    issues.push(buildAliasIssue({
+                        record,
+                        lineNumber: i + 1,
+                        heading: currentHeading,
+                        alias: alias.alias,
+                        canonical: pattern.term,
+                        key: pattern.key,
+                    }));
+                }
+            }
+        }
+    }
+    catch (error) {
+        notes.push(`Unable to scan ${record.path}: ${error.message ?? String(error)}`);
+    }
+    return { issues, canonicalHits, notes };
+};
+const groupCanonicalHits = (hits) => {
+    const grouped = new Map();
+    for (const hit of hits) {
+        const existing = grouped.get(hit.key);
+        if (existing) {
+            existing.push(hit);
+        }
+        else {
+            grouped.set(hit.key, [hit]);
+        }
+    }
+    return grouped;
+};
+export const runTerminologyNormalizationGate = async (input) => {
+    const glossary = input.glossary ?? loadGlossary();
+    if (!glossary.entries.length) {
+        return {
+            gateId: "gate-terminology-normalization",
+            gateName: "Terminology Normalization",
+            status: "skipped",
+            issues: [],
+            notes: ["Glossary is empty; terminology normalization skipped."],
+        };
+    }
+    const patterns = buildPatterns(glossary);
+    const records = [input.artifacts.pdr, input.artifacts.sds].filter((record) => Boolean(record));
+    if (records.length === 0) {
+        return {
+            gateId: "gate-terminology-normalization",
+            gateName: "Terminology Normalization",
+            status: "skipped",
+            issues: [],
+            notes: ["No PDR/SDS artifacts available for terminology checks."],
+        };
+    }
+    const issues = [];
+    const notes = [];
+    const canonicalHits = [];
+    for (const record of records) {
+        const result = await scanRecord(record, patterns);
+        issues.push(...result.issues);
+        canonicalHits.push(...result.canonicalHits);
+        notes.push(...result.notes);
+    }
+    const groupedHits = groupCanonicalHits(canonicalHits);
+    for (const group of CONTRADICTION_GROUPS) {
+        const hits = group.keys
+            .map((key) => groupedHits.get(key) ?? [])
+            .filter((entry) => entry.length > 0);
+        if (hits.length < 2)
+            continue;
+        const flattened = hits.flat();
+        const first = flattened[0];
+        const terms = hits.map((entry) => entry[0]?.term).filter(Boolean);
+        issues.push(buildContradictionIssue({
+            record: first.record,
+            lineNumber: first.lineNumber,
+            terms,
+            keys: group.keys,
+            label: group.label,
+        }));
+    }
+    const hasContradiction = issues.some((issue) => issue.severity === SEVERITY_CONTRADICTION);
+    const status = hasContradiction ? "fail" : issues.length > 0 ? "warn" : "pass";
+    return {
+        gateId: "gate-terminology-normalization",
+        gateName: "Terminology Normalization",
+        status,
+        issues,
+        notes: notes.length > 0 ? notes : undefined,
+        metadata: {
+            glossaryEntries: glossary.entries.length,
+            contradictionGroups: CONTRADICTION_GROUPS.length,
+        },
+    };
+};

package/dist/services/docs/review/glossary.json

@@ -0,0 +1,47 @@
+{
+    "version": 1,
+    "entries": [
+        {
+            "key": "consent_token",
+            "term": "consent token",
+            "description": "Install-time token issued to capture user consent, including TTL and revoke behavior.",
+            "aliases": ["consent id", "consent key", "consent handle"]
+        },
+        {
+            "key": "anonymous_token",
+            "term": "anonymous token",
+            "description": "Token that represents a user without storing direct identifiers.",
+            "aliases": ["anon token", "anonymous identifier"]
+        },
+        {
+            "key": "identified_token",
+            "term": "identified token",
+            "description": "Token tied to a known identity with explicit consent.",
+            "aliases": ["non-anonymous token", "identified id"]
+        },
+        {
+            "key": "policy_owner",
+            "term": "policy owner",
+            "description": "Role responsible for approving policy and cache rule changes.",
+            "aliases": ["policy maintainer", "policy steward"]
+        },
+        {
+            "key": "data_pipeline",
+            "term": "data pipeline",
+            "description": "End-to-end flow for ingestion, normalization, and storage.",
+            "aliases": ["pipeline", "processing pipeline"]
+        },
+        {
+            "key": "telemetry_metering",
+            "term": "telemetry metering",
+            "description": "Explicit rules for event capture limits, sampling, and rate enforcement.",
+            "aliases": ["usage metering", "event metering"]
+        }
+    ],
+    "canonicalPhrases": {
+        "consent_flow": "install-time consent token issuance and revoke flow",
+        "anonymity": "anonymous vs identified token handling",
+        "pipeline": "data pipeline with ownership for normalization rules",
+        "telemetry": "telemetry metering and sampling policy"
+    }
+}

package/dist/services/estimate/EstimateService.d.ts

@@ -4,6 +4,8 @@ export declare class EstimateService {
     private workspace;
     private constructor();
     static create(workspace: WorkspaceResolution): Promise<EstimateService>;
+    private safeDivide;
+    private computeElapsedLaneHours;
     private computeDurations;
     private computeEtas;
     estimate(options: Omit<EstimateOptions, "workspace">): Promise<EstimateResult>;

package/dist/services/estimate/EstimateService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EstimateService.d.ts","sourceRoot":"","sources":["../../../src/services/estimate/EstimateService.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAmC,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEnG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAI/E,qBAAa,eAAe;IACN,OAAO,CAAC,SAAS;IAArC,OAAO;WAEM,MAAM,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAI7E,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,WAAW;IAmBb,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC;IAmD9E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}
+{"version":3,"file":"EstimateService.d.ts","sourceRoot":"","sources":["../../../src/services/estimate/EstimateService.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAmC,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEnG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAI/E,qBAAa,eAAe;IACN,OAAO,CAAC,SAAS;IAArC,OAAO;WAEM,MAAM,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAI7E,OAAO,CAAC,UAAU;YAMJ,uBAAuB;IAmCrC,OAAO,CAAC,gBAAgB;IA8BxB,OAAO,CAAC,WAAW;IA+Bb,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC;IAwD9E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/services/estimate/EstimateService.js

@@ -1,3 +1,5 @@
+import { Connection } from "@mcoda/db";
+import { PathHelper } from "@mcoda/shared";
 import { BacklogService } from "../backlog/BacklogService.js";
 import { VelocityService } from "./VelocityService.js";
 const HOURS_IN_MS = 3600 * 1000;
@@ -8,18 +10,55 @@ export class EstimateService {
     static async create(workspace) {
         return new EstimateService(workspace);
     }
-    computeDurations(totals, velocity) {
-        const safeDivide = (sp, spPerHour) => {
-            if (!sp || sp <= 0)
-                return 0;
-            if (!spPerHour || spPerHour <= 0)
-                return null;
-            return sp / spPerHour;
-        };
-        const implementationHours = safeDivide(totals.implementation.story_points, velocity.implementationSpPerHour);
-        const reviewHours = safeDivide(totals.review.story_points, velocity.reviewSpPerHour);
-        const qaHours = safeDivide(totals.qa.story_points, velocity.qaSpPerHour);
-        const durationsList = [implementationHours, reviewHours, qaHours];
+    safeDivide(sp, spPerHour) {
+        if (!sp || sp <= 0)
+            return 0;
+        if (!spPerHour || spPerHour <= 0)
+            return null;
+        return sp / spPerHour;
+    }
+    async computeElapsedLaneHours(taskIds, status) {
+        if (taskIds.length === 0)
+            return 0;
+        const dbPath = PathHelper.getWorkspaceDbPath(this.workspace.workspaceRoot);
+        let connection;
+        try {
+            connection = await Connection.open(dbPath);
+            const placeholders = taskIds.map(() => "?").join(", ");
+            const rows = await connection.db.all(`SELECT task_id, MAX(timestamp) as started_at
+         FROM task_status_events
+         WHERE to_status = ?
+           AND task_id IN (${placeholders})
+         GROUP BY task_id`, status, ...taskIds);
+            const now = Date.now();
+            let totalMs = 0;
+            for (const row of rows) {
+                if (!row.started_at)
+                    continue;
+                const startMs = Date.parse(row.started_at);
+                if (!Number.isNaN(startMs) && startMs <= now) {
+                    totalMs += now - startMs;
+                }
+            }
+            return totalMs / HOURS_IN_MS;
+        }
+        catch {
+            return 0;
+        }
+        finally {
+            if (connection) {
+                await connection.close();
+            }
+        }
+    }
+    computeDurations(totals, velocity, elapsedImplementationHours) {
+        const implementationRaw = this.safeDivide(totals.implementation.story_points, velocity.implementationSpPerHour);
+        const implementationHours = implementationRaw === null ? null : Math.max((implementationRaw ?? 0) - elapsedImplementationHours, 0);
+        const reviewHours = this.safeDivide(totals.review.story_points, velocity.reviewSpPerHour);
+        const qaHours = this.safeDivide(totals.qa.story_points, velocity.qaSpPerHour);
+        const reviewPipelineHours = this.safeDivide(totals.implementation.story_points + totals.review.story_points, velocity.reviewSpPerHour);
+        const qaPipelineHours = this.safeDivide(totals.implementation.story_points + totals.review.story_points + totals.qa.story_points, velocity.qaSpPerHour);
+        const durationsList = [implementationHours, reviewPipelineHours, qaPipelineHours];
         const hasNull = durationsList.some((value) => value === null);
         const numeric = durationsList.filter((value) => value !== null);
         const totalHours = hasNull || numeric.length === 0 ? null : Math.max(...numeric);
@@ -30,18 +69,22 @@ export class EstimateService {
             totalHours,
         };
     }
-    computeEtas(durations) {
+    computeEtas(totals, velocity, durations) {
         const now = Date.now();
         const addHours = (hours) => {
             if (hours === null || hours === undefined || hours < 0)
                 return undefined;
             return new Date(now + hours * HOURS_IN_MS).toISOString();
         };
+        const reviewPipelineHours = this.safeDivide(totals.implementation.story_points + totals.review.story_points, velocity.reviewSpPerHour);
+        const qaPipelineHours = this.safeDivide(totals.implementation.story_points + totals.review.story_points + totals.qa.story_points, velocity.qaSpPerHour);
         const readyToReviewEta = durations.implementationHours !== null ? addHours(durations.implementationHours ?? undefined) : undefined;
-        const readyToQaEta = durations.implementationHours !== null && durations.reviewHours !== null
-            ? addHours(Math.max(durations.implementationHours ?? 0, durations.reviewHours ?? 0))
+        const readyToQaEta = durations.implementationHours !== null && reviewPipelineHours !== null
+            ? addHours(Math.max(durations.implementationHours ?? 0, reviewPipelineHours ?? 0))
+            : undefined;
+        const completeEta = durations.implementationHours !== null && reviewPipelineHours !== null && qaPipelineHours !== null
+            ? addHours(Math.max(durations.implementationHours ?? 0, reviewPipelineHours ?? 0, qaPipelineHours ?? 0))
             : undefined;
-        const completeEta = durations.totalHours !== null ? addHours(durations.totalHours ?? undefined) : undefined;
         return {
             readyToReviewEta,
             readyToQaEta,
@@ -51,6 +94,7 @@ export class EstimateService {
     async estimate(options) {
         const backlogService = await BacklogService.create(this.workspace);
         let backlogTotals;
+        let backlogTasks = [];
         try {
             const { summary } = await backlogService.getBacklog({
                 projectKey: options.projectKey,
@@ -59,6 +103,7 @@ export class EstimateService {
                 assignee: options.assignee,
             });
             backlogTotals = summary.totals;
+            backlogTasks = summary.tasks.map((task) => ({ task_id: task.task_id, status: task.status }));
         }
         finally {
             await backlogService.close();
@@ -74,6 +119,7 @@ export class EstimateService {
                 mode: options.mode,
                 windowTasks: options.windowTasks,
                 spPerHourAll: options.spPerHourAll,
+                spPerHourImplementation: options.spPerHourImplementation,
                 spPerHourReview: options.spPerHourReview,
                 spPerHourQa: options.spPerHourQa,
             });
@@ -81,8 +127,10 @@ export class EstimateService {
         finally {
             await velocityService.close();
         }
-        const durationsHours = this.computeDurations(backlogTotals, effectiveVelocity);
-        const etas = this.computeEtas(durationsHours);
+        const inProgressTaskIds = backlogTasks.filter((task) => task.status === "in_progress").map((task) => task.task_id);
+        const elapsedImplementationHours = await this.computeElapsedLaneHours(inProgressTaskIds, "in_progress");
+        const durationsHours = this.computeDurations(backlogTotals, effectiveVelocity, elapsedImplementationHours);
+        const etas = this.computeEtas(backlogTotals, effectiveVelocity, durationsHours);
         return {
             scope: {
                 workspaceId: this.workspace.workspaceId,

package/dist/services/estimate/VelocityService.d.ts

@@ -12,6 +12,10 @@ export declare class VelocityService {
     private resolveConfig;
     private resolveScopeIds;
     private buildTaskFilters;
+    private insertStatusEvent;
+    private maybeBackfillStatusEvents;
+    private computeLaneVelocityFromTaskRuns;
+    private computeLaneVelocityFromStatusEvents;
     private computeLaneVelocity;
     private deriveDurationSeconds;
     getEffectiveVelocity(options?: VelocityOptions): Promise<EffectiveVelocity>;

package/dist/services/estimate/VelocityService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VelocityService.d.ts","sourceRoot":"","sources":["../../../src/services/estimate/VelocityService.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAkB,eAAe,EAAoB,MAAM,YAAY,CAAC;AAKvG,qBAAa,eAAe;IAExB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,cAAc,CAAC;IAJzB,OAAO;WAOM,MAAM,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAOvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;mBAIP,wBAAwB;IAiB7C,OAAO,CAAC,aAAa;YAoCP,eAAe;IAgC7B,OAAO,CAAC,gBAAgB;YAuBV,mBAAmB;IAmEjC,OAAO,CAAC,qBAAqB;IAQvB,oBAAoB,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA2DtF"}
+{"version":3,"file":"VelocityService.d.ts","sourceRoot":"","sources":["../../../src/services/estimate/VelocityService.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAkB,eAAe,EAAoB,MAAM,YAAY,CAAC;AAKvG,qBAAa,eAAe;IAExB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,cAAc,CAAC;IAJzB,OAAO;WAOM,MAAM,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAOvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;mBAIP,wBAAwB;IAiB7C,OAAO,CAAC,aAAa;YAuCP,eAAe;IAgC7B,OAAO,CAAC,gBAAgB;YAuBV,iBAAiB;YA2BjB,yBAAyB;YAsHzB,+BAA+B;YAmD/B,mCAAmC;YAoEnC,mBAAmB;IAqBjC,OAAO,CAAC,qBAAqB;IAQvB,oBAAoB,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAmFtF"}