@devtrack-solution/codesdd 1.2.2 → 1.2.3

package/dist/core/sdd/governance-backfill.js

@@ -0,0 +1,359 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import * as yaml from 'yaml';
+import { adrFrontmatterSchema, debateFrontmatterSchema, discardedFrontmatterSchema, epicFrontmatterSchema, insightFrontmatterSchema, } from './governance-schemas.js';
+const GOVERNANCE_STATUSES = new Set([
+    'NEW',
+    'OPEN',
+    'DEBATED',
+    'PROMOTED',
+    'DROPPED',
+    'APPROVED',
+    'DISCARDED',
+    'SUPERSEDED',
+    'READY',
+    'PLANNED',
+    'IN_PROGRESS',
+    'DONE',
+    'CANCELLED',
+]);
+const DISCOVERY_DIRS = [
+    { type: 'INS', relDir: '.sdd/discovery/1-insights' },
+    { type: 'DEB', relDir: '.sdd/discovery/2-debates' },
+    { type: 'EPIC', relDir: '.sdd/discovery/3-epic' },
+    { type: 'Discarded', relDir: '.sdd/discovery/4-discarded' },
+];
+function emptyBucket() {
+    return { inspected: 0, updated: 0, skipped: 0, exceptions: [] };
+}
+function relPath(projectRoot, filePath) {
+    return path.relative(projectRoot, filePath).replace(/\\/gu, '/');
+}
+function hasFrontmatter(content) {
+    return /^---\r?\n/u.test(content);
+}
+function frontmatterDocument(frontmatter, body) {
+    return `---\n${yaml.stringify(frontmatter).trim()}\n---\n${body}`;
+}
+function normalizeStatus(value, fallback) {
+    if (typeof value === 'string' && GOVERNANCE_STATUSES.has(value))
+        return value;
+    return fallback;
+}
+function normalizeTimestamp(value, fallback) {
+    if (typeof value === 'string' && Number.isFinite(Date.parse(value))) {
+        return new Date(value).toISOString();
+    }
+    if (value instanceof Date && Number.isFinite(value.getTime())) {
+        return value.toISOString();
+    }
+    return fallback;
+}
+function stripMarkdown(value) {
+    return value
+        .replace(/[`*_]+/gu, '')
+        .replace(/\[[^\]]+\]\(([^)]+)\)/gu, '$1')
+        .replace(/\s+/gu, ' ')
+        .trim();
+}
+function extractHeadingTitle(content, id) {
+    const heading = content.match(/^#\s+(.+)$/mu)?.[1];
+    if (!heading)
+        return id;
+    return stripMarkdown(heading
+        .replace(new RegExp(`\\b${id}\\b`, 'u'), '')
+        .replace(/^[:\-\s]+/u, '')
+        .replace(/^(Insight|Debate|Epic|Radar|ADR)\s*/iu, '')
+        .trim()) || id;
+}
+function extractSection(content, headingPattern) {
+    const lines = content.split(/\r?\n/u);
+    const start = lines.findIndex((line) => headingPattern.test(line.trim()));
+    if (start === -1)
+        return '';
+    const sectionLines = [];
+    for (let index = start + 1; index < lines.length; index++) {
+        if (/^##\s+/u.test(lines[index].trim()))
+            break;
+        sectionLines.push(lines[index]);
+    }
+    return sectionLines.join('\n').trim();
+}
+function extractBulletLines(section) {
+    return section
+        .split(/\r?\n/u)
+        .map((line) => line.trim().replace(/^[-*]\s*/u, '').trim())
+        .filter(Boolean);
+}
+function firstParagraph(section, fallback) {
+    const paragraph = section
+        .split(/\r?\n\r?\n/u)
+        .map((part) => stripMarkdown(part.replace(/^[-*]\s*/gmu, '')))
+        .find(Boolean);
+    return paragraph || fallback;
+}
+function normalizeOptionId(value, fallback = 'A') {
+    const match = String(value || '').match(/[A-Z]/u)?.[0];
+    return match || fallback;
+}
+function idFromFile(filePath) {
+    return path.basename(filePath).match(/\b(?:INS|DEB|EPIC|FEAT)-\d{3,4}\b/u)?.[0] ?? path.basename(filePath, '.md');
+}
+function discoverySchemaFor(frontmatter) {
+    if (frontmatter.artifact_type === 'INS')
+        return insightFrontmatterSchema;
+    if (frontmatter.artifact_type === 'DEB')
+        return debateFrontmatterSchema;
+    if (frontmatter.artifact_type === 'EPIC')
+        return epicFrontmatterSchema;
+    return discardedFrontmatterSchema;
+}
+function buildCommonDiscovery(type, id, content, record, fallbackNow) {
+    const relatedIds = Array.isArray(record?.related_ids) ? record.related_ids.filter(Boolean) : [];
+    const title = record?.title || extractHeadingTitle(content, id);
+    const createdAt = normalizeTimestamp(record?.created_at, fallbackNow);
+    const updatedAt = normalizeTimestamp(record?.updated_at, createdAt);
+    const origin = type === 'DEB'
+        ? { type: 'insight', ref: relatedIds.find((value) => /^INS-\d{3,4}$/u.test(value)) }
+        : type === 'EPIC'
+            ? { type: 'debate', ref: relatedIds.find((value) => /^DEB-\d{3,4}$/u.test(value)) }
+            : type === 'Discarded'
+                ? { type: 'debate', ref: relatedIds.find((value) => /^DEB-\d{3,4}$/u.test(value)) || id }
+                : { type: 'user_prompt' };
+    return {
+        schema_version: 1,
+        id,
+        title,
+        ...(record?.title_canonical ? { title_canonical: record.title_canonical } : {}),
+        status: normalizeStatus(record?.status, type === 'EPIC' ? 'READY' : type === 'Discarded' ? 'DISCARDED' : 'NEW'),
+        origin: origin.ref ? origin : { type: origin.type },
+        related_ids: relatedIds,
+        created_at: createdAt,
+        updated_at: updatedAt,
+    };
+}
+function buildInsightFrontmatter(id, content, record, fallbackNow) {
+    const common = buildCommonDiscovery('INS', id, content, record, fallbackNow);
+    return insightFrontmatterSchema.parse({
+        ...common,
+        artifact_type: 'INS',
+        id,
+        promoted_to: common.related_ids.find((value) => !value.startsWith('INS-')),
+    });
+}
+function buildDebateFrontmatter(id, content, record, fallbackNow, exceptions, file) {
+    const common = buildCommonDiscovery('DEB', id, content, record, fallbackNow);
+    const questionSection = extractSection(content, /^##\s*1\)?\s*Decision Question/iu);
+    const criteriaSection = extractSection(content, /^##\s*2\)?\s*Decision Criteria/iu);
+    const options = Array.from(content.matchAll(/^###\s+(?:Option|Opcao|Opção)\s+([A-Z])/gmu)).map((match) => ({
+        id: normalizeOptionId(match[1]),
+        label: `Option ${normalizeOptionId(match[1])}`,
+    }));
+    const choiceLine = content.match(/(?:Choice|Escolha)(?:\s*\([^)]*\))?[:* ]+\s*([A-Z])/iu);
+    const choice = normalizeOptionId(choiceLine?.[1] || options[0]?.id || 'A');
+    const optionIds = new Set(options.map((option) => option.id));
+    optionIds.add(choice);
+    if (optionIds.size < 2) {
+        optionIds.add(choice === 'A' ? 'B' : 'A');
+        exceptions.push({ scope: 'discovery', file, id, reason: 'Debate options were defaulted from legacy body.', severity: 'warning' });
+    }
+    if (!choiceLine) {
+        exceptions.push({ scope: 'discovery', file, id, reason: 'Mediator choice was defaulted from legacy body.', severity: 'warning' });
+    }
+    const rationaleMatch = content.match(/(?:Rationale|Racional|Justificativa):\s*(.+)$/imu);
+    const rationale = stripMarkdown(rationaleMatch?.[1] || '') || 'Backfilled from legacy debate body; see Markdown body for full rationale.';
+    const output = common.status === 'DISCARDED' ? 'DISCARDED' : 'APPROVED';
+    return debateFrontmatterSchema.parse({
+        ...common,
+        artifact_type: 'DEB',
+        id,
+        status: normalizeStatus(common.status, 'OPEN'),
+        decision: {
+            question: firstParagraph(questionSection, `Decide ${common.title}.`),
+            options: Array.from(optionIds).sort().map((optionId) => ({
+                id: optionId,
+                label: options.find((option) => option.id === optionId)?.label || `Option ${optionId}`,
+            })),
+            criteria: extractBulletLines(criteriaSection),
+            scoring: [],
+            mediator: {
+                choice,
+                rationale,
+                accepted_risks: [],
+                reversal_conditions: [],
+            },
+            output,
+        },
+    });
+}
+function buildEpicFrontmatter(id, content, record, fallbackNow) {
+    const common = buildCommonDiscovery('EPIC', id, content, record, fallbackNow);
+    const summarySection = extractSection(content, /^##\s*Approved Summary/iu) || extractSection(content, /^##\s*Resumo aprovado/iu);
+    return epicFrontmatterSchema.parse({
+        ...common,
+        artifact_type: 'EPIC',
+        id,
+        status: normalizeStatus(common.status, 'READY'),
+        approved_summary: firstParagraph(summarySection, common.title),
+        quality_contract: {
+            scope: 'touched_scope',
+            unit_target_percent: 95,
+            integration_target_percent: 95,
+            evidence_mode: 'hybrid',
+        },
+        lock_domains: [],
+        produces: [],
+        consumes: [],
+        breakdown_policy: 'graph',
+    });
+}
+function buildDiscardedFrontmatter(id, content, record, fallbackNow) {
+    const common = buildCommonDiscovery('Discarded', id, content, record, fallbackNow);
+    const reasonSection = extractSection(content, /^##\s*Discard Reason/iu) || extractSection(content, /^##\s*Raz[aã]o/iu);
+    return discardedFrontmatterSchema.parse({
+        ...common,
+        artifact_type: 'Discarded',
+        id,
+        status: 'DISCARDED',
+        discarded_from: id,
+        discard_reason: firstParagraph(reasonSection, 'Backfilled from legacy discarded artifact.'),
+        discarded_at: common.updated_at,
+        discarded_by: 'codesdd backfill',
+    });
+}
+function buildAdrFrontmatter(filePath, content, feature, fallbackNow) {
+    const featureId = idFromFile(filePath);
+    const refs = [featureId, feature?.origin_ref].filter((value) => Boolean(value));
+    const headingTitle = extractHeadingTitle(content, featureId);
+    const createdFromBody = content.match(/(?:Created at|Finalized at|Finalizado em):\s*([^\n]+)/iu)?.[1]?.trim();
+    const createdAt = normalizeTimestamp(createdFromBody || feature?.done_at || feature?.archived_at, fallbackNow);
+    const updatedAt = normalizeTimestamp(feature?.done_at || feature?.archived_at || createdAt, createdAt);
+    const status = normalizeStatus(feature?.status, feature?.done_at || feature?.archived_at ? 'DONE' : 'IN_PROGRESS');
+    const decisionStatus = status === 'DONE' ? 'ACCEPTED' : status === 'CANCELLED' ? 'SUPERSEDED' : 'PROPOSED';
+    const referencesSection = extractSection(content, /^##\s*References/iu) || extractSection(content, /^##\s*Refs/iu) || refs.join(', ');
+    const references = extractBulletLines(referencesSection)
+        .flatMap((line) => line.split(','))
+        .map((line) => line.trim())
+        .filter(Boolean);
+    return adrFrontmatterSchema.parse({
+        schema_version: 1,
+        artifact_type: 'ADR',
+        id: `ADR-${featureId}`,
+        feature_id: featureId,
+        title: feature?.title ? `ADR ${featureId}: ${feature.title}` : `ADR ${featureId}: ${headingTitle}`,
+        status,
+        origin: { type: 'feature', ref: featureId },
+        related_ids: refs,
+        created_at: createdAt,
+        updated_at: updatedAt,
+        decision_status: decisionStatus,
+        supersedes: [],
+        superseded_by: [],
+        references: references.length > 0 ? references : refs,
+    });
+}
+async function listMarkdownFiles(dirPath) {
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isFile() && path.extname(entry.name).toLowerCase() === '.md')
+            .map((entry) => path.join(dirPath, entry.name))
+            .sort((left, right) => left.localeCompare(right));
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+async function loadYamlDocument(filePath, fallback) {
+    try {
+        return yaml.parse(await fs.readFile(filePath, 'utf-8'));
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return fallback;
+        throw error;
+    }
+}
+async function backfillDiscovery(projectRoot, write, now) {
+    const bucket = emptyBucket();
+    const discoveryIndex = await loadYamlDocument(path.join(projectRoot, '.sdd/state/discovery-index.yaml'), { records: [] });
+    const records = new Map((discoveryIndex.records || []).map((record) => [record.id, record]));
+    for (const group of DISCOVERY_DIRS) {
+        for (const filePath of await listMarkdownFiles(path.join(projectRoot, group.relDir))) {
+            bucket.inspected++;
+            const content = await fs.readFile(filePath, 'utf-8');
+            const file = relPath(projectRoot, filePath);
+            if (hasFrontmatter(content)) {
+                bucket.skipped++;
+                continue;
+            }
+            const id = idFromFile(filePath);
+            const record = records.get(id);
+            if (!record) {
+                bucket.exceptions.push({ scope: 'discovery', file, id, reason: 'No discovery-index record found; using file body fallback fields.', severity: 'warning' });
+            }
+            const frontmatter = group.type === 'INS'
+                ? buildInsightFrontmatter(id, content, record, now)
+                : group.type === 'DEB'
+                    ? buildDebateFrontmatter(id, content, record, now, bucket.exceptions, file)
+                    : group.type === 'EPIC'
+                        ? buildEpicFrontmatter(id, content, record, now)
+                        : buildDiscardedFrontmatter(id, content, record, now);
+            discoverySchemaFor(frontmatter).parse(frontmatter);
+            if (write)
+                await fs.writeFile(filePath, frontmatterDocument(frontmatter, content), 'utf-8');
+            bucket.updated++;
+        }
+    }
+    return bucket;
+}
+async function backfillAdrs(projectRoot, write, now) {
+    const bucket = emptyBucket();
+    const backlog = await loadYamlDocument(path.join(projectRoot, '.sdd/state/backlog.yaml'), {
+        items: [],
+    });
+    const features = new Map((backlog.items || []).map((item) => [item.id, item]));
+    for (const filePath of await listMarkdownFiles(path.join(projectRoot, '.sdd/core/adrs'))) {
+        bucket.inspected++;
+        const content = await fs.readFile(filePath, 'utf-8');
+        const file = relPath(projectRoot, filePath);
+        if (hasFrontmatter(content)) {
+            bucket.skipped++;
+            continue;
+        }
+        const featureId = idFromFile(filePath);
+        const feature = features.get(featureId);
+        if (!feature) {
+            bucket.exceptions.push({ scope: 'adr', file, id: featureId, reason: 'No backlog record found; using ADR body fallback fields.', severity: 'warning' });
+        }
+        const frontmatter = buildAdrFrontmatter(filePath, content, feature, now);
+        if (write)
+            await fs.writeFile(filePath, frontmatterDocument(frontmatter, content), 'utf-8');
+        bucket.updated++;
+    }
+    return bucket;
+}
+export async function backfillGovernanceFrontmatter(options) {
+    const now = options.nowIso || new Date().toISOString();
+    const write = options.write === true;
+    const report = {
+        generated_at: now,
+        write,
+        discovery: emptyBucket(),
+        adr: emptyBucket(),
+    };
+    if (options.discovery !== false) {
+        report.discovery = await backfillDiscovery(options.projectRoot, write, now);
+    }
+    if (options.adr !== false) {
+        report.adr = await backfillAdrs(options.projectRoot, write, now);
+    }
+    if (options.reportPath) {
+        await fs.mkdir(path.dirname(options.reportPath), { recursive: true });
+        await fs.writeFile(options.reportPath, yaml.stringify(report), 'utf-8');
+    }
+    return report;
+}
+//# sourceMappingURL=governance-backfill.js.map

package/dist/core/sdd/governance-parser.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export type GovernanceFormat = 'frontmatter-md' | 'legacy-md';
+export interface ParsedGovernanceFile<T> {
+    frontmatter: T | null;
+    body: string;
+    hasFrontmatter: boolean;
+    format: GovernanceFormat;
+    rawPath: string;
+}
+type GovernanceParseErrorKind = 'invalid_yaml' | 'schema_violation' | 'invalid_delimiter';
+export declare class GovernanceParseError extends Error {
+    readonly kind: GovernanceParseErrorKind;
+    readonly rawPath: string;
+    readonly detail: string;
+    readonly line?: number;
+    constructor(kind: GovernanceParseErrorKind, rawPath: string, detail: string, line?: number);
+}
+export declare function parseGovernanceFile<T>(rawPath: string, content: string, schema?: z.ZodType<T>): ParsedGovernanceFile<T>;
+export declare function parseGovernanceDir<T>(dirPath: string, schema: z.ZodType<T>): Promise<Array<ParsedGovernanceFile<T>>>;
+export {};
+//# sourceMappingURL=governance-parser.d.ts.map

package/dist/core/sdd/governance-parser.js

@@ -0,0 +1,91 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { parseDocument } from 'yaml';
+const FRONTMATTER_OPENING_PATTERN = /^---\r?\n/;
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/;
+export class GovernanceParseError extends Error {
+    kind;
+    rawPath;
+    detail;
+    line;
+    constructor(kind, rawPath, detail, line) {
+        super(`${kind} at ${rawPath}${line ? `:${line}` : ''} - ${detail}`);
+        this.name = 'GovernanceParseError';
+        this.kind = kind;
+        this.rawPath = rawPath;
+        this.detail = detail;
+        this.line = line;
+    }
+}
+function issuePath(issue) {
+    const pathText = issue.path?.length ? issue.path.join('.') : '(root)';
+    return `${pathText}: ${issue.message}`;
+}
+function yamlErrorLine(error, source) {
+    const linePos = error.linePos?.[0]?.line;
+    if (typeof linePos === 'number')
+        return linePos;
+    const offset = error.pos?.[0];
+    if (typeof offset !== 'number')
+        return undefined;
+    return source.slice(0, offset).split(/\r\n|\r|\n/u).length;
+}
+export function parseGovernanceFile(rawPath, content, schema) {
+    if (FRONTMATTER_OPENING_PATTERN.test(content) && !FRONTMATTER_PATTERN.test(content)) {
+        throw new GovernanceParseError('invalid_delimiter', rawPath, 'Frontmatter opening delimiter found without a closing delimiter on its own line.');
+    }
+    const match = FRONTMATTER_PATTERN.exec(content);
+    if (!match) {
+        return {
+            frontmatter: null,
+            body: content,
+            hasFrontmatter: false,
+            format: 'legacy-md',
+            rawPath,
+        };
+    }
+    const frontmatterRaw = match[1];
+    const body = content.slice(match[0].length);
+    const yamlDoc = parseDocument(frontmatterRaw, { prettyErrors: false });
+    if (yamlDoc.errors.length > 0) {
+        const firstError = yamlDoc.errors[0];
+        const line = yamlErrorLine(firstError, frontmatterRaw);
+        throw new GovernanceParseError('invalid_yaml', rawPath, firstError.message, line);
+    }
+    const parsedYaml = yamlDoc.toJSON();
+    if (schema) {
+        const result = schema.safeParse(parsedYaml);
+        if (!result.success) {
+            const firstIssue = result.error.issues[0];
+            throw new GovernanceParseError('schema_violation', rawPath, issuePath(firstIssue));
+        }
+        return {
+            frontmatter: result.data,
+            body,
+            hasFrontmatter: true,
+            format: 'frontmatter-md',
+            rawPath,
+        };
+    }
+    return {
+        frontmatter: parsedYaml,
+        body,
+        hasFrontmatter: true,
+        format: 'frontmatter-md',
+        rawPath,
+    };
+}
+export async function parseGovernanceDir(dirPath, schema) {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    const files = entries
+        .filter((entry) => entry.isFile() && path.extname(entry.name).toLowerCase() === '.md')
+        .map((entry) => path.join(dirPath, entry.name))
+        .sort((left, right) => left.localeCompare(right));
+    const parsed = [];
+    for (const filePath of files) {
+        const content = await fs.readFile(filePath, 'utf-8');
+        parsed.push(parseGovernanceFile(filePath, content, schema));
+    }
+    return parsed;
+}
+//# sourceMappingURL=governance-parser.js.map