@devtrack-solution/codesdd 1.2.2

package/dist/core/sdd/lenses.d.ts

@@ -0,0 +1,14 @@
+export interface StructuralLens {
+    artifact_type: string;
+    name: string;
+    required_sections: string[];
+    forbidden_phrases?: string[];
+    section_rules?: Record<string, {
+        min_lines?: number;
+        min_length?: number;
+    }>;
+}
+export declare const LENSES: Record<string, StructuralLens>;
+export declare function extractSectionContent(content: string, sectionHeader: string): string;
+export declare function validateDocumentAgainstLens(content: string, lens: StructuralLens): string[];
+//# sourceMappingURL=lenses.d.ts.map

package/dist/core/sdd/lenses.js

@@ -0,0 +1,97 @@
+export const LENSES = {
+    insight: {
+        artifact_type: 'INS',
+        name: 'Insight Lens',
+        required_sections: ['## Title', '## Description'],
+        section_rules: {
+            '## Description': { min_length: 100 },
+        },
+    },
+    debate: {
+        artifact_type: 'DEB',
+        name: 'Debate Lens',
+        required_sections: [
+            '## 1) Decision Question (Required)',
+            '## 2) Decision Criteria (Required)',
+            '## 3) Options Considered (Minimum 2)',
+            '### Option A',
+            '### Option B',
+            '## 6) Scoring Matrix (0-5)',
+            '## 7) Mediator Decision (Required)',
+            '- Choice (A/B/C):',
+            '- Rationale:',
+            '## 8) Quality Contract (Required)',
+            '## 9) Output',
+        ],
+        forbidden_phrases: ['(fill in', 'Describe the result'],
+    },
+    epic: {
+        artifact_type: 'EPIC',
+        name: 'Epic Lens',
+        required_sections: ['## Origin', '## Approved Summary', '## Status'],
+        forbidden_phrases: ['(fill in approved summary)'],
+    },
+    adr: {
+        artifact_type: 'ADR',
+        name: 'ADR Lens',
+        required_sections: ['## Context', '## Decision', '## Consequences'],
+        forbidden_phrases: ['(fill in context)'],
+    },
+};
+export function extractSectionContent(content, sectionHeader) {
+    // Encontra a seção especificada e pega tudo até o próximo header de mesmo ou maior nível,
+    const lines = content.split('\n');
+    const startIndex = lines.findIndex(l => l.trim() === sectionHeader);
+    if (startIndex === -1) {
+        // Tenta encontrar cabecalho parcial caso o template tenha adicionado sufixo
+        const partialIndex = lines.findIndex(l => l.trim().startsWith(sectionHeader));
+        if (partialIndex === -1)
+            return '';
+        return extractFromLines(lines, partialIndex);
+    }
+    return extractFromLines(lines, startIndex);
+}
+function extractFromLines(lines, startIndex) {
+    const contentLines = [];
+    for (let i = startIndex + 1; i < lines.length; i++) {
+        if (lines[i].trim().startsWith('#'))
+            break;
+        contentLines.push(lines[i]);
+    }
+    return contentLines.join('\n').trim();
+}
+export function validateDocumentAgainstLens(content, lens) {
+    const missing = lens.required_sections.filter((section) => !content.includes(section));
+    const violations = [...missing];
+    if (lens.forbidden_phrases) {
+        for (const phrase of lens.forbidden_phrases) {
+            if (content.includes(phrase)) {
+                violations.push(`Frase proibida encontrada: "${phrase}"`);
+            }
+        }
+    }
+    if (lens.section_rules) {
+        for (const [sectionHeader, rules] of Object.entries(lens.section_rules)) {
+            if (missing.includes(sectionHeader))
+                continue;
+            const sectionContent = extractSectionContent(content, sectionHeader);
+            if (rules.min_length !== undefined && sectionContent.length < rules.min_length) {
+                violations.push(`Seção "${sectionHeader}" requer no mínimo ${rules.min_length} caracteres, encontrado: ${sectionContent.length}`);
+            }
+            if (rules.min_lines !== undefined) {
+                // Ignora linhas de listas vazias e placeholders para a checagem real
+                const validLines = sectionContent.split('\n')
+                    .map(l => l.trim())
+                    .filter(l => l.length > 0 && l !== '-' && !l.startsWith('- [ ]') && !l.includes('preencher') && !l.includes('TODO'));
+                if (validLines.length < rules.min_lines) {
+                    violations.push(`Seção "${sectionHeader}" requer no mínimo ${rules.min_lines} linhas de conteúdo não vazio, encontrado:\n${sectionContent}`);
+                }
+            }
+        }
+    }
+    if (violations.length > 0) {
+        console.log('LENS VIOLATIONS:', violations);
+    }
+    return violations;
+}
+//# sourceMappingURL=lenses.js.map

package/dist/core/sdd/merge-catalog.d.ts

@@ -0,0 +1,9 @@
+import type { ArchitectureNode, FrontendDecisionRecord, RepoMapRecord, ServiceRecord, TechStackRecord } from './types.js';
+export declare function stableUniqueStrings(values: string[]): string[];
+export declare function upsertByKey<T>(items: T[], incoming: T, keyFor: (item: T) => string, merge: (existing: T, next: T) => T): void;
+export declare function mergeArchitectureNode(existing: ArchitectureNode, incoming: ArchitectureNode): ArchitectureNode;
+export declare function mergeServiceRecord(existing: ServiceRecord, incoming: ServiceRecord): ServiceRecord;
+export declare function mergeTechStackRecord(existing: TechStackRecord, incoming: TechStackRecord): TechStackRecord;
+export declare function mergeRepoMapRecord(existing: RepoMapRecord, incoming: RepoMapRecord): RepoMapRecord;
+export declare function mergeFrontendDecisionRecord(existing: FrontendDecisionRecord, incoming: FrontendDecisionRecord): FrontendDecisionRecord;
+//# sourceMappingURL=merge-catalog.d.ts.map

package/dist/core/sdd/merge-catalog.js

@@ -0,0 +1,70 @@
+export function stableUniqueStrings(values) {
+    return Array.from(new Set(values.filter((value) => value && value.trim().length > 0)));
+}
+function preferExisting(existing, incoming) {
+    const existingValue = existing?.trim() || '';
+    if (existingValue)
+        return existingValue;
+    return incoming?.trim() || '';
+}
+export function upsertByKey(items, incoming, keyFor, merge) {
+    const index = items.findIndex((item) => keyFor(item) === keyFor(incoming));
+    if (index < 0) {
+        items.push(incoming);
+        return;
+    }
+    items[index] = merge(items[index], incoming);
+}
+export function mergeArchitectureNode(existing, incoming) {
+    return {
+        ...existing,
+        name: preferExisting(existing.name, incoming.name),
+        kind: preferExisting(existing.kind, incoming.kind),
+        description: preferExisting(existing.description, incoming.description),
+        repo_paths: stableUniqueStrings([...existing.repo_paths, ...incoming.repo_paths]),
+        depends_on: stableUniqueStrings([...existing.depends_on, ...incoming.depends_on]),
+    };
+}
+export function mergeServiceRecord(existing, incoming) {
+    return {
+        ...existing,
+        name: preferExisting(existing.name, incoming.name),
+        responsibility: preferExisting(existing.responsibility, incoming.responsibility),
+        owner_refs: stableUniqueStrings([...existing.owner_refs, ...incoming.owner_refs]),
+        repo_paths: stableUniqueStrings([...existing.repo_paths, ...incoming.repo_paths]),
+        contracts: stableUniqueStrings([...existing.contracts, ...incoming.contracts]),
+        external_dependencies: stableUniqueStrings([
+            ...existing.external_dependencies,
+            ...incoming.external_dependencies,
+        ]),
+    };
+}
+export function mergeTechStackRecord(existing, incoming) {
+    return {
+        ...existing,
+        version: preferExisting(existing.version, incoming.version),
+        purpose: preferExisting(existing.purpose, incoming.purpose),
+        constraints: stableUniqueStrings([...existing.constraints, ...incoming.constraints]),
+    };
+}
+export function mergeRepoMapRecord(existing, incoming) {
+    return {
+        ...existing,
+        kind: preferExisting(existing.kind, incoming.kind),
+        service_ref: preferExisting(existing.service_ref, incoming.service_ref),
+        notes: preferExisting(existing.notes, incoming.notes),
+    };
+}
+export function mergeFrontendDecisionRecord(existing, incoming) {
+    return {
+        ...existing,
+        title: preferExisting(existing.title, incoming.title),
+        status: existing.status || incoming.status,
+        decision: preferExisting(existing.decision, incoming.decision),
+        rationale: preferExisting(existing.rationale, incoming.rationale),
+        related_refs: stableUniqueStrings([...existing.related_refs, ...incoming.related_refs]),
+        route_refs: stableUniqueStrings([...existing.route_refs, ...incoming.route_refs]),
+        adr_refs: stableUniqueStrings([...existing.adr_refs, ...incoming.adr_refs]),
+    };
+}
+//# sourceMappingURL=merge-catalog.js.map

package/dist/core/sdd/migrate-workspace.d.ts

@@ -0,0 +1,36 @@
+type WorkspaceDocKind = 'spec' | 'plan' | 'tasks' | 'changelog' | 'quality';
+export type WorkspaceMigrationFileResult = {
+    source: string;
+    target: string;
+    kind: WorkspaceDocKind;
+    written: boolean;
+    removedSource: boolean;
+    missingFields: string[];
+    validationErrors: string[];
+};
+export type WorkspaceMigrationFeatureResult = {
+    featureId: string;
+    root: 'planned' | 'active' | 'archived';
+    workspace: string;
+    files: WorkspaceMigrationFileResult[];
+};
+export type WorkspaceMigrationResult = {
+    dryRun: boolean;
+    scanned: number;
+    migrated: number;
+    features: WorkspaceMigrationFeatureResult[];
+    incomplete: Array<{
+        featureId: string;
+        file: string;
+        fields: string[];
+    }>;
+};
+export declare function findMarkdownWorkspaceFiles(projectRoot: string, feat?: string): Promise<string[]>;
+export declare class MigrateWorkspaceCommand {
+    execute(projectRoot: string, options?: {
+        dryRun?: boolean;
+        feat?: string;
+    }): Promise<WorkspaceMigrationResult>;
+}
+export {};
+//# sourceMappingURL=migrate-workspace.d.ts.map

package/dist/core/sdd/migrate-workspace.js

@@ -0,0 +1,344 @@
+import path from 'node:path';
+import { existsSync, promises as fs } from 'node:fs';
+import { stringify as stringifyYaml } from 'yaml';
+import { loadProjectSddConfig, resolveSddPaths } from './state.js';
+import { workspaceChangelogSchema, workspacePlanSchema, workspaceQualitySchema, workspaceSpecSchema, workspaceTasksSchema, } from './workspace-schemas.js';
+const MIGRATION_MARKER = '# MIGRATION: field required but source had no content';
+const CANONICAL_DOCS = [
+    '1-spec',
+    '1-especificacao',
+    '2-plan',
+    '2-planejamento',
+    '3-tasks',
+    '3-tarefas',
+    '4-changelog',
+    '5-quality',
+    'quality',
+];
+export async function findMarkdownWorkspaceFiles(projectRoot, feat) {
+    const config = await loadProjectSddConfig(projectRoot);
+    const paths = resolveSddPaths(projectRoot, config);
+    const files = [];
+    for (const root of [paths.plannedDir, paths.activeDir, paths.archivedDir]) {
+        for (const workspace of await listFeatureWorkspaces(root, feat)) {
+            const entries = await fs.readdir(workspace.path, { withFileTypes: true }).catch(() => []);
+            for (const entry of entries) {
+                if (!entry.isFile() || path.extname(entry.name) !== '.md')
+                    continue;
+                if (!canonicalDocKind(entry.name))
+                    continue;
+                files.push(path.join(workspace.path, entry.name));
+            }
+        }
+    }
+    return files.sort();
+}
+export class MigrateWorkspaceCommand {
+    async execute(projectRoot, options) {
+        const config = await loadProjectSddConfig(projectRoot);
+        const paths = resolveSddPaths(projectRoot, config);
+        const dryRun = Boolean(options?.dryRun);
+        const features = [];
+        for (const [rootName, rootPath] of [
+            ['planned', paths.plannedDir],
+            ['active', paths.activeDir],
+            ['archived', paths.archivedDir],
+        ]) {
+            for (const workspace of await listFeatureWorkspaces(rootPath, options?.feat)) {
+                const fileResults = [];
+                const entries = await fs.readdir(workspace.path, { withFileTypes: true }).catch(() => []);
+                for (const entry of entries) {
+                    if (!entry.isFile() || path.extname(entry.name) !== '.md')
+                        continue;
+                    const kind = canonicalDocKind(entry.name);
+                    if (!kind)
+                        continue;
+                    const sourcePath = path.join(workspace.path, entry.name);
+                    const raw = await fs.readFile(sourcePath, 'utf-8');
+                    const migrated = migrateMarkdownDocument(workspace.featureId, kind, raw);
+                    const targetPath = path.join(workspace.path, migrated.targetName);
+                    let written = false;
+                    let removedSource = false;
+                    if (!dryRun) {
+                        await fs.writeFile(targetPath, renderYamlWithMigrationComments(migrated.document, migrated.missingFields), 'utf-8');
+                        written = true;
+                        await fs.rm(sourcePath, { force: true });
+                        removedSource = true;
+                    }
+                    fileResults.push({
+                        source: rel(paths, sourcePath),
+                        target: rel(paths, targetPath),
+                        kind,
+                        written,
+                        removedSource,
+                        missingFields: migrated.missingFields,
+                        validationErrors: migrated.validationErrors,
+                    });
+                }
+                if (fileResults.length > 0) {
+                    features.push({
+                        featureId: workspace.featureId,
+                        root: rootName,
+                        workspace: rel(paths, workspace.path),
+                        files: fileResults,
+                    });
+                }
+            }
+        }
+        return {
+            dryRun,
+            scanned: features.length,
+            migrated: features.reduce((total, feature) => total + feature.files.filter((file) => file.written).length, 0),
+            features,
+            incomplete: features.flatMap((feature) => feature.files
+                .filter((file) => file.missingFields.length > 0 || file.validationErrors.length > 0)
+                .map((file) => ({
+                featureId: feature.featureId,
+                file: file.target,
+                fields: [...file.missingFields, ...file.validationErrors],
+            }))),
+        };
+    }
+}
+async function listFeatureWorkspaces(rootPath, feat) {
+    if (!existsSync(rootPath))
+        return [];
+    const entries = await fs.readdir(rootPath, { withFileTypes: true }).catch(() => []);
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .filter((entry) => /^FEAT-\d{4}$/.test(entry.name))
+        .filter((entry) => !feat || entry.name === feat)
+        .map((entry) => ({ featureId: entry.name, path: path.join(rootPath, entry.name) }))
+        .sort((a, b) => a.featureId.localeCompare(b.featureId));
+}
+function canonicalDocKind(fileName) {
+    const base = path.basename(fileName, '.md');
+    if (!CANONICAL_DOCS.includes(base))
+        return undefined;
+    if (base.startsWith('1-'))
+        return 'spec';
+    if (base.startsWith('2-'))
+        return 'plan';
+    if (base.startsWith('3-'))
+        return 'tasks';
+    if (base.startsWith('4-'))
+        return 'changelog';
+    return 'quality';
+}
+function migrateMarkdownDocument(featureId, kind, markdown) {
+    const parsed = parseMarkdown(markdown);
+    if (kind === 'spec')
+        return migrateSpec(featureId, parsed);
+    if (kind === 'plan')
+        return migratePlan(featureId, parsed);
+    if (kind === 'tasks')
+        return migrateTasks(featureId, parsed);
+    if (kind === 'changelog')
+        return migrateChangelog(featureId, parsed);
+    return migrateQuality(featureId, parsed);
+}
+function parseMarkdown(markdown) {
+    const sections = new Map();
+    const lines = markdown.replace(/\r\n/g, '\n').split('\n');
+    let title = '';
+    let current = '';
+    let buffer = [];
+    const flush = () => {
+        if (current)
+            sections.set(normalizeHeading(current), buffer.join('\n').trim());
+    };
+    for (const line of lines) {
+        const heading = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+        if (heading) {
+            if (!title && heading[1] === '#')
+                title = heading[2].trim();
+            flush();
+            current = heading[2].trim();
+            buffer = [];
+            continue;
+        }
+        if (current)
+            buffer.push(line);
+    }
+    flush();
+    const bullets = lines
+        .map((line) => line.trim())
+        .filter((line) => /^[-*]\s+/.test(line))
+        .map((line) => line.replace(/^[-*]\s+/, '').trim())
+        .filter(Boolean);
+    return { title, body: markdown.trim(), sections, bullets };
+}
+function migrateSpec(featureId, parsed) {
+    const missing = [];
+    const title = ensureText(featureId, 'title', parsed.title || section(parsed, ['title', 'titulo']), 10, missing);
+    const objective = ensureText(featureId, 'objective', section(parsed, ['objective', 'objetivo', 'summary', 'resumo']), 100, missing);
+    const expected = ensureText(featureId, 'expected_outcome', section(parsed, ['expected outcome', 'resultado esperado', 'outcome']), 50, missing);
+    const impact = ensureText(featureId, 'system_impact', section(parsed, ['system impact', 'impacto sistêmico', 'impacto sistemico']), 30, missing);
+    const doc = {
+        schema_version: 1,
+        feature_id: featureId,
+        title,
+        origin: { type: 'direct', ref: featureId },
+        objective,
+        expected_outcome: expected,
+        system_impact: impact,
+        acceptance_refs: parsed.bullets.length > 0 ? parsed.bullets.slice(0, 5) : [featureId],
+        gates: defaultGates(),
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+    };
+    return withValidation('1-spec.yaml', doc, missing, workspaceSpecSchema);
+}
+function migratePlan(featureId, parsed) {
+    const missing = [];
+    const affected = parsed.bullets.length > 0 ? parsed.bullets.slice(0, 6) : ['migration'];
+    const doc = {
+        schema_version: 1,
+        feature_id: featureId,
+        architectural_impact: {
+            description: ensureText(featureId, 'architectural_impact.description', section(parsed, ['architectural impact', 'impacto arquitetural', 'plan', 'plano']), 1, missing),
+            affected_modules: affected,
+        },
+        frontend_impact: {
+            status: 'unknown',
+            description: ensureText(featureId, 'frontend_impact.description', section(parsed, ['frontend impact', 'impacto frontend']), 1, missing),
+        },
+        affected_contracts: [],
+        quality_strategy: {
+            unit_target: 95,
+            integration_target: 95,
+            approach: 'hybrid',
+        },
+        suggested_skills: [],
+    };
+    return withValidation('2-plan.yaml', doc, missing, workspacePlanSchema);
+}
+function migrateTasks(featureId, parsed) {
+    const phases = ['preparation', 'implementation', 'testing', 'documentation', 'finalization'];
+    const sourceTasks = parsed.bullets.length > 0 ? parsed.bullets : parsed.body.split('\n').filter((line) => line.trim());
+    const doc = {
+        schema_version: 1,
+        feature_id: featureId,
+        tasks: phases.map((phase, index) => {
+            const source = sourceTasks[index] || `${phase} migration task`;
+            return {
+                id: `${featureId}-MIG-${index + 1}`,
+                phase,
+                title: source.slice(0, 80),
+                description: source,
+                files_touched: [],
+                test_scripts: phase === 'testing'
+                    ? [{ command: 'pnpm test', type: 'test', expected: 'Migration validation passes.' }]
+                    : [],
+                acceptance: `Migrated ${phase} task is reviewed for completeness.`,
+                status: 'pending',
+            };
+        }),
+    };
+    return withValidation('3-tasks.yaml', doc, [], workspaceTasksSchema);
+}
+function migrateChangelog(featureId, parsed) {
+    const entries = parsed.bullets.length > 0 ? parsed.bullets : [parsed.body || 'Legacy changelog migrated.'];
+    const doc = {
+        schema_version: 1,
+        feature_id: featureId,
+        entries: entries.map((details) => ({
+            timestamp: new Date().toISOString(),
+            action: 'migrated',
+            details,
+            refs: [],
+        })),
+    };
+    return withValidation('4-changelog.yaml', doc, [], workspaceChangelogSchema);
+}
+function migrateQuality(featureId, parsed) {
+    const missing = [];
+    const evidence = parsed.bullets.length > 0 ? parsed.bullets : [];
+    const doc = {
+        schema_version: 1,
+        feature_id: featureId,
+        coverage_targets: { unit: 95, integration: 95 },
+        validation_strategies: [
+            {
+                name: 'Migrated validation',
+                command: 'pnpm test',
+                expected: ensureText(featureId, 'validation_strategies[0].expected', section(parsed, ['validation', 'validacao', 'quality', 'qualidade']), 1, missing),
+            },
+        ],
+        evidence_log: evidence.map((result) => ({
+            timestamp: new Date().toISOString(),
+            kind: 'migrated',
+            result,
+        })),
+        skill_evidence: {
+            required_skill_ids: [],
+            evidence: [],
+            verification_rule: 'No skill evidence required for migrated legacy workspaces.',
+        },
+        acceptance_matrix: [
+            {
+                criterion: 'migrated-quality-review',
+                status: evidence.length > 0 ? 'met' : 'not_met',
+                evidence: evidence.join('; ') || `${MIGRATION_MARKER}: quality evidence`,
+            },
+        ],
+        exceptions: [],
+        remediation_policy: { on_coverage_miss: 'block', max_rounds: 3 },
+        traceability: {
+            spec_anchor: {
+                spec_updated_at: '',
+                changelog_refs: ['migrated'],
+            },
+            requirements: [],
+        },
+    };
+    return withValidation('5-quality.yaml', doc, missing, workspaceQualitySchema);
+}
+function section(parsed, names) {
+    for (const name of names) {
+        const value = parsed.sections.get(normalizeHeading(name));
+        if (value)
+            return value;
+    }
+    return '';
+}
+function normalizeHeading(value) {
+    return value
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .trim()
+        .toLowerCase();
+}
+function ensureText(featureId, field, value, minLength, missing) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    if (normalized.length >= minLength)
+        return normalized;
+    missing.push(field);
+    const fallback = `${MIGRATION_MARKER}: ${field} for ${featureId}. Review the migrated workspace and replace this placeholder with source-specific content before relying on the artifact.`;
+    return fallback.length >= minLength ? fallback : fallback.padEnd(minLength, '.');
+}
+function defaultGates() {
+    return {
+        proposta: { status: 'rascunho' },
+        planejamento: { status: 'rascunho' },
+        tarefas: { status: 'rascunho' },
+    };
+}
+function withValidation(targetName, document, missingFields, schema) {
+    const validation = schema.safeParse(document);
+    return {
+        targetName,
+        document,
+        missingFields,
+        validationErrors: validation.success ? [] : [validation.error.message],
+    };
+}
+function renderYamlWithMigrationComments(document, missingFields) {
+    const comments = missingFields.map((field) => `${MIGRATION_MARKER}: ${field}`);
+    const prefix = comments.length > 0 ? `${comments.join('\n')}\n` : '';
+    return `${prefix}${stringifyYaml(document)}`;
+}
+function rel(paths, filePath) {
+    return path.relative(paths.projectRoot, filePath).replace(/\\/g, '/');
+}
+//# sourceMappingURL=migrate-workspace.js.map

package/dist/core/sdd/migrate.d.ts

@@ -0,0 +1,24 @@
+export declare const CURRENT_SDD_STATE_VERSION = 2;
+export interface SddMigrationAssessment {
+    currentVersion: number;
+    targetVersion: number;
+    needsMigration: boolean;
+    reasons: string[];
+    conversions: Array<{
+        from: string;
+        to: string;
+    }>;
+    legacyRecords: string[];
+    workspaceMarkdownFiles: string[];
+}
+export declare function assessSddMigration(projectRoot: string): Promise<SddMigrationAssessment>;
+export declare class SddMigrateCommand {
+    execute(projectRoot: string, options?: {
+        radToEpic?: boolean;
+    }): Promise<{
+        converted: number;
+        messages: string[];
+        assessment: SddMigrationAssessment;
+    }>;
+}
+//# sourceMappingURL=migrate.d.ts.map