@specatlas/core 0.1.22 → 0.1.24

package/dist/index.d.ts

@@ -1708,6 +1708,148 @@ interface ArchiveResult {
 declare function archiveChange(opts: ArchiveOptions): Promise<ArchiveResult>;
 declare function regenerateIndex(root: string, cfg?: AtlasConfig, now?: Date): Promise<void>;
 
+declare const SCHEMA_VERSION = 1;
+declare const BACKUP_DIRNAME = ".backup";
+declare const BACKUP_POINTER = ".latest";
+interface MigrationSpec {
+    id: string;
+    description: string;
+    from: number;
+    to: number;
+}
+declare const SCHEMA_MIGRATIONS: MigrationSpec[];
+interface UpgradeItem {
+    artifact: string;
+    path: string;
+    from: number;
+    to: number;
+    migration: string;
+    summary: string;
+}
+interface UpgradeIssue {
+    artifact: string;
+    path: string;
+    reason: string;
+}
+interface UpgradePlan {
+    root: string;
+    currentVersion: number;
+    pending: UpgradeItem[];
+    newer: UpgradeIssue[];
+    unreadable: UpgradeIssue[];
+    upToDate: boolean;
+}
+interface FoundArtifact {
+    artifact: string;
+    path: string;
+}
+declare function collectVersionedArtifacts(root: string): Promise<FoundArtifact[]>;
+type ArtifactVersionState = {
+    state: 'ok';
+    version: number;
+} | {
+    state: 'absent';
+} | {
+    state: 'unreadable';
+    reason: string;
+};
+declare function readArtifactVersion(content: string): ArtifactVersionState;
+declare function stampSchemaVersion(content: string, version: number): string | undefined;
+declare function planUpgrade(root: string): Promise<UpgradePlan>;
+interface UpgradeBackupInfo {
+    name: string;
+    dir: string;
+    relativeDir: string;
+    createdAt: string;
+    files: string[];
+}
+interface UpgradeApplyReport {
+    status: 'applied' | 'up-to-date' | 'failed';
+    plan: UpgradePlan;
+    applied: UpgradeItem[];
+    backup?: UpgradeBackupInfo;
+    failure?: {
+        artifact: string;
+        message: string;
+    };
+}
+declare function applyUpgrade(root: string, now?: Date): Promise<UpgradeApplyReport>;
+interface UpgradeRollbackReport {
+    status: 'restored' | 'no-backup' | 'failed';
+    restored: string[];
+    backup?: string;
+    failure?: {
+        artifact: string;
+        message: string;
+    };
+}
+declare function rollbackUpgrade(root: string): Promise<UpgradeRollbackReport>;
+interface UpgradeAdvisory {
+    plan: UpgradePlan;
+    diagnostics: Diagnostic[];
+}
+declare function upgradeAdvisory(root: string): Promise<UpgradeAdvisory>;
+
+declare const SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+declare const SARIF_VERSION = "2.1.0";
+declare const TOOL_NAME = "SpecAtlas";
+declare const TOOL_URL = "https://github.com/AlonsoAM/specatlas";
+interface SarifOptions {
+    diagnostics: readonly Diagnostic[];
+    root: string;
+    version: string;
+    failed?: boolean;
+}
+interface SarifRule {
+    id: string;
+    shortDescription: {
+        text: string;
+    };
+    help?: {
+        text: string;
+    };
+}
+interface SarifLocation {
+    physicalLocation: {
+        artifactLocation: {
+            uri: string;
+        };
+        region?: {
+            startLine: number;
+        };
+    };
+}
+interface SarifResult {
+    ruleId: string;
+    level: 'error' | 'warning' | 'note';
+    message: {
+        text: string;
+    };
+    locations?: SarifLocation[];
+}
+interface SarifReport {
+    $schema: string;
+    version: string;
+    runs: Array<{
+        tool: {
+            driver: {
+                name: string;
+                informationUri: string;
+                version: string;
+                rules: SarifRule[];
+            };
+        };
+        results: SarifResult[];
+        invocations: Array<{
+            executionSuccessful: boolean;
+        }>;
+    }>;
+}
+declare function ruleDescription(code: string): string;
+declare function sarifLevel(severity: Diagnostic['severity']): SarifResult['level'];
+declare function toSarifReport(opts: SarifOptions): SarifReport;
+declare function toSarifText(opts: SarifOptions): string;
+
 interface DoctorReport {
     findings: Diagnostic[];
     summary: {
@@ -1747,4 +1889,4 @@ declare function livingRequirementsMap(specs: Array<{
 }>): Map<string, Requirement>;
 declare function runCiGate(opts: CiOptions): Promise<CiResult>;
 
-export { type AdoptDomain, type AdoptOptions, type AdoptResult, type AgingBucket, type AnalyzeOptions, type AnalyzePackSummary, type AnalyzeResult, type Approval, type ApprovalStatus, type ApprovalsFile, type ApprovalsIndex, type ApproveFromGithubOptions, type ApproveFromGithubResult, type ArchiveOptions, type ArchiveResult, type AtlasConfig, type AttentionItem, BLOCK_HEAD_RE, BUILTIN_PACKS, type BlockWavePlan, CONFIG_FILE, CORE_VERSION, type CaptureResult, type Change, type ChangeMeta, type ChangeMetrics, type ChangeState, type CiCheck, type CiExtraCheck, type CiOptions, type CiResult, type Delta, type DeltaOp, type DeriveInput, type DerivedState, type DetectionResult, type Diagnostic, type DoctorReport, type Domain, type Evidence, type EvidenceMethod, type EvidenceResult, type ExecOptions, type ExecResult, type FoldOutcome, type FrontmatterResult, type GhRunner, type GitHubRepo, type GlossaryTerm, type ImpactEvidence, type ImpactReport, type ImpactTask, type InitOptions, type InitResult, type IssueBodyInput, type Lane, type Language, type LinkedIssue, type LintOptions, type LoadedConfig, type MockupCheckResult, type MockupManifest, type MockupPlan, type MockupPlanScreen, type MockupScreen, type MoveOps, type NewChangeOptions, type NewChangeResult, type NextAction, type Override, type Pack, type PackCheck, type PackCheckResult, type PackCheckType, type PackEvaluation, type ParsedGlossary, type PresentOptions, type PresentResult, type ProfileMatch, REQ_HEAD_RE, REQ_ID_RE, RULE_ID_RE, RULE_RE, RUN_EVENT_TYPES, type RecordEvidenceOptions, type RecordEvidenceResult, type Rename, type Requirement, type RiskLevel, type Rule, type RunEvent, type RunEventType, type RunRecord, type RunState, type RunStatus, SCENARIO_HEAD_RE, SCENARIO_ID_RE, SDD_DIR, SLUG_RE, type Scenario, type Severity, type SignApprovalOptions, type SignApprovalResult, type SpecFile, type SpecRef, type StackProfile, type SyncGithubOptions, type SyncGithubResult, TASK_ID_RE, TASK_LINE_RE, type Task, type TaskBlock, type TasksFile, type TemplateSet, type TraceEdge, type TraceFinding, type TraceGraph, type TraceInput, type TraceNode, type TraceResult, type VerifyFile, type WalkEntry, type WavePlan, type Workspace, type WorkspaceMetrics, adoptWorkspace, appendRunEvent, approvalsSchema, approveFromGithub, archiveChange, artifactHash, atlasConfigSchema, buildTraceGraph, canonicalizeMarkdown, captureMockups, changeMarker, changeMetaSchema, changeMetaYaml, checkMockups, checkTrace, collectMetrics, commentIssue, compareTaskIds, computeInputsHash, configToYaml, copyFile, countBySeverity, createChange, createIssue, createRun, defaultConfig, deriveState, detectProfiles, detectRepo, detectionToYaml, diag, editIssue, emitFrontmatter, ensureDir, ensureSddDirs, esc, evaluatePacks, evidenceSummary, exists, findLinkedIssue, findWorkspaceRoot, firstToken, foldDelta, generatePresentation, generateRunId, getNumber, getString, ghAuthStatus, ghAvailable, hasErrors, hasShellMetacharacters, impactOfFile, impactOfRequirement, indexMarkdown, initWorkspace, inline, isCommandAllowed, isDirectory, issueBody, issueLabels, laneOrDefault, lintDelta, lintMockupHtml, lintMockupManifest, lintPlan, lintRequirement, lintSpec, lintTasks, lintVerify, listChangeSlugs, listDir, listDirs, listRuns, livingRequirementsMap, loadActiveProfile, loadApprovals, loadChange, loadConfig, loadDetectedBest, loadProfileFile, loadProfilesFromDir, loadProjectPacks, loadSpecs, loadWorkspace, localCompact, localDate, localMonth, localOffset, localStamp, matchGlob, mockupManifestSchema, mockupsDir, mockupsReady, moveDirectory, packFindings, parseApprovals, parseChangeMeta, parseConfig, parseDelta, parseFrontmatter, parseGitHubRemote, parseGlossary, parseIssueUrl, parseRequirementBlocks, parseSpecFile, parseTasksFile, parseVerifyFile, patchChangeMeta, planBlock, planMockups, planWaves, profileSchema, readMockupManifest, readRun, readText, readTextIfExists, recordEvidence, regenerateIndex, renderMarkdown, renderRequirement, renderTemplate, requiresMockups, resolvePacks, runAnalyze, runCiGate, runDoctor, runProcess, setMockupRequirement, sha256, shortHash, signApproval, specHashOf, splitCommand, stateLabel, syncGithubIssue, templatesFor, toPosix, tokensFile, updateMockupScreenshots, updateRunStatus, verifyApproval, walkFiles, writeConfig, writeMockupManifest, writeMockupPlan, writeText };
+export { type AdoptDomain, type AdoptOptions, type AdoptResult, type AgingBucket, type AnalyzeOptions, type AnalyzePackSummary, type AnalyzeResult, type Approval, type ApprovalStatus, type ApprovalsFile, type ApprovalsIndex, type ApproveFromGithubOptions, type ApproveFromGithubResult, type ArchiveOptions, type ArchiveResult, type AtlasConfig, type AttentionItem, BACKUP_DIRNAME, BACKUP_POINTER, BLOCK_HEAD_RE, BUILTIN_PACKS, type BlockWavePlan, CONFIG_FILE, CORE_VERSION, type CaptureResult, type Change, type ChangeMeta, type ChangeMetrics, type ChangeState, type CiCheck, type CiExtraCheck, type CiOptions, type CiResult, type Delta, type DeltaOp, type DeriveInput, type DerivedState, type DetectionResult, type Diagnostic, type DoctorReport, type Domain, type Evidence, type EvidenceMethod, type EvidenceResult, type ExecOptions, type ExecResult, type FoldOutcome, type FrontmatterResult, type GhRunner, type GitHubRepo, type GlossaryTerm, type ImpactEvidence, type ImpactReport, type ImpactTask, type InitOptions, type InitResult, type IssueBodyInput, type Lane, type Language, type LinkedIssue, type LintOptions, type LoadedConfig, type MigrationSpec, type MockupCheckResult, type MockupManifest, type MockupPlan, type MockupPlanScreen, type MockupScreen, type MoveOps, type NewChangeOptions, type NewChangeResult, type NextAction, type Override, type Pack, type PackCheck, type PackCheckResult, type PackCheckType, type PackEvaluation, type ParsedGlossary, type PresentOptions, type PresentResult, type ProfileMatch, REQ_HEAD_RE, REQ_ID_RE, RULE_ID_RE, RULE_RE, RUN_EVENT_TYPES, type RecordEvidenceOptions, type RecordEvidenceResult, type Rename, type Requirement, type RiskLevel, type Rule, type RunEvent, type RunEventType, type RunRecord, type RunState, type RunStatus, SARIF_SCHEMA, SARIF_VERSION, SCENARIO_HEAD_RE, SCENARIO_ID_RE, SCHEMA_MIGRATIONS, SCHEMA_VERSION, SDD_DIR, SLUG_RE, type SarifLocation, type SarifOptions, type SarifReport, type SarifResult, type SarifRule, type Scenario, type Severity, type SignApprovalOptions, type SignApprovalResult, type SpecFile, type SpecRef, type StackProfile, type SyncGithubOptions, type SyncGithubResult, TASK_ID_RE, TASK_LINE_RE, TOOL_NAME, TOOL_URL, type Task, type TaskBlock, type TasksFile, type TemplateSet, type TraceEdge, type TraceFinding, type TraceGraph, type TraceInput, type TraceNode, type TraceResult, type UpgradeAdvisory, type UpgradeApplyReport, type UpgradeBackupInfo, type UpgradeIssue, type UpgradeItem, type UpgradePlan, type UpgradeRollbackReport, type VerifyFile, type WalkEntry, type WavePlan, type Workspace, type WorkspaceMetrics, adoptWorkspace, appendRunEvent, applyUpgrade, approvalsSchema, approveFromGithub, archiveChange, artifactHash, atlasConfigSchema, buildTraceGraph, canonicalizeMarkdown, captureMockups, changeMarker, changeMetaSchema, changeMetaYaml, checkMockups, checkTrace, collectMetrics, collectVersionedArtifacts, commentIssue, compareTaskIds, computeInputsHash, configToYaml, copyFile, countBySeverity, createChange, createIssue, createRun, defaultConfig, deriveState, detectProfiles, detectRepo, detectionToYaml, diag, editIssue, emitFrontmatter, ensureDir, ensureSddDirs, esc, evaluatePacks, evidenceSummary, exists, findLinkedIssue, findWorkspaceRoot, firstToken, foldDelta, generatePresentation, generateRunId, getNumber, getString, ghAuthStatus, ghAvailable, hasErrors, hasShellMetacharacters, impactOfFile, impactOfRequirement, indexMarkdown, initWorkspace, inline, isCommandAllowed, isDirectory, issueBody, issueLabels, laneOrDefault, lintDelta, lintMockupHtml, lintMockupManifest, lintPlan, lintRequirement, lintSpec, lintTasks, lintVerify, listChangeSlugs, listDir, listDirs, listRuns, livingRequirementsMap, loadActiveProfile, loadApprovals, loadChange, loadConfig, loadDetectedBest, loadProfileFile, loadProfilesFromDir, loadProjectPacks, loadSpecs, loadWorkspace, localCompact, localDate, localMonth, localOffset, localStamp, matchGlob, mockupManifestSchema, mockupsDir, mockupsReady, moveDirectory, packFindings, parseApprovals, parseChangeMeta, parseConfig, parseDelta, parseFrontmatter, parseGitHubRemote, parseGlossary, parseIssueUrl, parseRequirementBlocks, parseSpecFile, parseTasksFile, parseVerifyFile, patchChangeMeta, planBlock, planMockups, planUpgrade, planWaves, profileSchema, readArtifactVersion, readMockupManifest, readRun, readText, readTextIfExists, recordEvidence, regenerateIndex, renderMarkdown, renderRequirement, renderTemplate, requiresMockups, resolvePacks, rollbackUpgrade, ruleDescription, runAnalyze, runCiGate, runDoctor, runProcess, sarifLevel, setMockupRequirement, sha256, shortHash, signApproval, specHashOf, splitCommand, stampSchemaVersion, stateLabel, syncGithubIssue, templatesFor, toPosix, toSarifReport, toSarifText, tokensFile, updateMockupScreenshots, updateRunStatus, upgradeAdvisory, verifyApproval, walkFiles, writeConfig, writeMockupManifest, writeMockupPlan, writeText };

package/dist/index.js

@@ -794,14 +794,14 @@ function wordBoundary(text, term) {
   const re = new RegExp(`(?<![\\p{L}\\p{N}])${escaped}(?![\\p{L}\\p{N}])`, "iu");
   return re.test(text);
 }
-function lintText(text, code, terms, label, path19, line) {
+function lintText(text, code, terms, label, path21, line) {
   const out = [];
   const lower = text.toLowerCase();
   for (const term of terms) {
     if (wordBoundary(lower, term)) {
       out.push(
         diag(code, "error", `${label}: "${term}"`, {
-          path: path19,
+          path: path21,
           line,
           suggestion: "La especificaci\xF3n es funcional y de negocio: describe comportamiento, no tecnolog\xEDa ni adjetivos vagos"
         })
@@ -810,7 +810,7 @@ function lintText(text, code, terms, label, path19, line) {
   }
   return out;
 }
-function lintRequirement(req, path19, opts = {}) {
+function lintRequirement(req, path21, opts = {}) {
   const out = [];
   const vague = opts.language === "en" ? VAGUE_EN : VAGUE_ES;
   const tech = opts.language === "en" ? TECH_EN : TECH_ES;
@@ -821,32 +821,32 @@ function lintRequirement(req, path19, opts = {}) {
     ...req.scenarios.flatMap((s) => [...s.when.map((w) => ({ text: w, line: s.line })), ...s.then.map((t) => ({ text: t, line: s.line }))])
   ];
   for (const part of parts) {
-    out.push(...lintText(part.text, "LINT-BIZ-002", vague, "Palabra vaga en la especificaci\xF3n", path19, part.line));
+    out.push(...lintText(part.text, "LINT-BIZ-002", vague, "Palabra vaga en la especificaci\xF3n", path21, part.line));
     if (opts.businessOnly !== false) {
-      out.push(...lintText(part.text, "LINT-BIZ-001", tech, "Jerga t\xE9cnica en la especificaci\xF3n de negocio", path19, part.line));
+      out.push(...lintText(part.text, "LINT-BIZ-001", tech, "Jerga t\xE9cnica en la especificaci\xF3n de negocio", path21, part.line));
     }
   }
   if (req.scenarios.length === 0) {
-    out.push(diag("TRACE-001", "error", `El requisito ${req.id} no tiene ning\xFAn escenario`, { path: path19, line: req.line, suggestion: "A\xF1ade al menos un escenario CUANDO/ENTONCES" }));
+    out.push(diag("TRACE-001", "error", `El requisito ${req.id} no tiene ning\xFAn escenario`, { path: path21, line: req.line, suggestion: "A\xF1ade al menos un escenario CUANDO/ENTONCES" }));
   }
   return out;
 }
-function lintDelta(delta, livingRequirements, path19, opts = {}) {
+function lintDelta(delta, livingRequirements, path21, opts = {}) {
   const out = [...delta.diagnostics];
   for (const req of [...delta.added, ...delta.modified]) {
-    out.push(...lintRequirement(req, path19, opts));
+    out.push(...lintRequirement(req, path21, opts));
   }
   for (const req of delta.modified) {
     const living = livingRequirements.get(req.id);
     if (!living) {
-      out.push(diag("TRACE-007", "error", `MODIFIED ${req.id} no existe en la spec viva; usa ADDED`, { path: path19, line: req.line }));
+      out.push(diag("TRACE-007", "error", `MODIFIED ${req.id} no existe en la spec viva; usa ADDED`, { path: path21, line: req.line }));
       continue;
     }
     for (const existing of living.scenarios) {
       if (!req.scenarios.some((s) => s.id === existing.id)) {
         out.push(
           diag("TRACE-007", "error", `MODIFIED ${req.id} pierde el escenario ${existing.id}: copia el bloque completo`, {
-            path: path19,
+            path: path21,
             line: req.line,
             suggestion: "Copia el bloque completo de la spec viva y ed\xEDtalo; para quitarlo, decl\xE1ralo en REMOVED"
           })
@@ -857,15 +857,15 @@ function lintDelta(delta, livingRequirements, path19, opts = {}) {
   for (const req of delta.removed) {
     const living = livingRequirements.get(req.id);
     if (!living) {
-      out.push(diag("TRACE-007", "error", `REMOVED ${req.id} no existe en la spec viva`, { path: path19, line: req.line }));
+      out.push(diag("TRACE-007", "error", `REMOVED ${req.id} no existe en la spec viva`, { path: path21, line: req.line }));
     }
   }
   for (const rename2 of delta.renamed) {
     if (rename2.from.id !== rename2.to.id) {
-      out.push(diag("LINT-DLT-003", "error", `RENAMED cambia el id (${rename2.from.id} \u2192 ${rename2.to.id}); los ids son inmutables`, { path: path19, line: rename2.line }));
+      out.push(diag("LINT-DLT-003", "error", `RENAMED cambia el id (${rename2.from.id} \u2192 ${rename2.to.id}); los ids son inmutables`, { path: path21, line: rename2.line }));
     }
     if (!livingRequirements.has(rename2.from.id)) {
-      out.push(diag("TRACE-007", "error", `RENAMED ${rename2.from.id} no existe en la spec viva`, { path: path19, line: rename2.line }));
+      out.push(diag("TRACE-007", "error", `RENAMED ${rename2.from.id} no existe en la spec viva`, { path: path21, line: rename2.line }));
     }
   }
   return out;
@@ -895,7 +895,7 @@ var MERMAID_KEYWORDS = [
   "architecture-beta"
 ];
 var MERMAID_BLOCKS = /^\s*(alt|loop|opt|par|rect|critical|break|subgraph)\b/;
-function lintPlan(planText, path19) {
+function lintPlan(planText, path21) {
   const out = [];
   const blocks = [...planText.matchAll(/```mermaid\r?\n([\s\S]*?)```/g)];
   for (const [index, block] of blocks.entries()) {
@@ -905,7 +905,7 @@ function lintPlan(planText, path19) {
     if (!MERMAID_KEYWORDS.some((keyword) => first.startsWith(keyword))) {
       out.push(
         diag("LINT-PLN-002", "error", `Diagrama mermaid ${index + 1}: la primera l\xEDnea debe declarar el tipo (${MERMAID_KEYWORDS.slice(0, 5).join(", ")}\u2026) y empieza por "${first.slice(0, 30)}"`, {
-          path: path19,
+          path: path21,
           suggestion: "Corrige el tipo del diagrama o elimina el bloque"
         })
       );
@@ -919,7 +919,7 @@ function lintPlan(planText, path19) {
     if (open !== 0) {
       out.push(
         diag("LINT-PLN-002", "error", `Diagrama mermaid ${index + 1}: faltan ${Math.abs(open)} \`end\` (bloques alt/loop/subgraph sin cerrar)`, {
-          path: path19,
+          path: path21,
           suggestion: "Cierra cada bloque alt/loop/opt/par/rect/subgraph con `end`"
         })
       );
@@ -931,7 +931,7 @@ function lintPlan(planText, path19) {
         if (message.includes(";")) {
           out.push(
             diag("LINT-PLN-003", "error", `Diagrama mermaid ${index + 1}: el mensaje "${message.trim().slice(0, 40)}\u2026" usa \`;\` y mermaid lo interpreta como fin de sentencia`, {
-              path: path19,
+              path: path21,
               suggestion: "Sustituye `;` por `\xB7` o `,` en los mensajes de sequenceDiagram"
             })
           );
@@ -4151,8 +4151,361 @@ async function regenerateIndex(root, cfg, now = /* @__PURE__ */ new Date()) {
   await writeText(path16.join(root, ".sdd", "INDEX.md"), markdown);
 }
 
-// src/doctor.ts
+// src/migrations.ts
+import { promises as fs2 } from "fs";
 import path17 from "path";
+import { parse as parseYaml8, stringify as stringifyYaml5 } from "yaml";
+var SCHEMA_VERSION = 1;
+var BACKUP_DIRNAME = ".backup";
+var BACKUP_POINTER = ".latest";
+var SCHEMA_MIGRATIONS = [
+  {
+    id: "0001-sellar-version-de-esquema",
+    description: "Sella la versi\xF3n de esquema vigente en los elementos que no la declaran",
+    from: 0,
+    to: SCHEMA_VERSION
+  }
+];
+var FIXED_ARTIFACTS = ["config.yaml", "approvals.yaml", path17.join("profiles", "detected.yaml")];
+var CHANGE_ARTIFACTS = ["meta.yaml", path17.join("mockups", "manifest.yaml")];
+async function pushChangeArtifacts(out, sddDir, relDir) {
+  for (const rel of CHANGE_ARTIFACTS) {
+    const abs = path17.join(sddDir, relDir, rel);
+    if (await exists(abs)) out.push({ artifact: toPosix(path17.join(relDir, rel)), path: abs });
+  }
+}
+async function collectVersionedArtifacts(root) {
+  const sddDir = path17.join(root, ".sdd");
+  const out = [];
+  for (const rel of FIXED_ARTIFACTS) {
+    const abs = path17.join(sddDir, rel);
+    if (await exists(abs)) out.push({ artifact: toPosix(rel), path: abs });
+  }
+  const changesDir = path17.join(sddDir, "changes");
+  for (const slug of await listDirs(changesDir)) {
+    if (slug === "archive") continue;
+    await pushChangeArtifacts(out, sddDir, path17.join("changes", slug));
+  }
+  for (const entry of await listDirs(path17.join(changesDir, "archive"))) {
+    await pushChangeArtifacts(out, sddDir, path17.join("changes", "archive", entry));
+  }
+  return out;
+}
+function readArtifactVersion(content) {
+  let data;
+  try {
+    data = parseYaml8(content);
+  } catch (err) {
+    return { state: "unreadable", reason: `YAML inv\xE1lido (${err.message})` };
+  }
+  if (data === null || data === void 0) return { state: "absent" };
+  if (typeof data !== "object" || Array.isArray(data)) return { state: "unreadable", reason: "la ra\xEDz no es un mapa de claves y valores" };
+  const raw = data["schema_version"];
+  if (raw === void 0) return { state: "absent" };
+  if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1) return { state: "unreadable", reason: `schema_version con valor no v\xE1lido: ${String(raw)}` };
+  return { state: "ok", version: raw };
+}
+function stampSchemaVersion(content, version) {
+  const line = `schema_version: ${version}`;
+  const bom = content.startsWith("\uFEFF") ? "\uFEFF" : "";
+  const body = bom ? content.slice(1) : content;
+  if (body.trim() === "") return `${bom}${line}
+`;
+  const eol = body.includes("\r\n") ? "\r\n" : "\n";
+  const lines = body.split(/\r?\n/);
+  const trailing = lines.length > 1 && lines[lines.length - 1] === "";
+  let index = 0;
+  while (index < lines.length) {
+    const trimmed = (lines[index] ?? "").trim();
+    if (trimmed === "" || trimmed.startsWith("#")) {
+      index += 1;
+      continue;
+    }
+    break;
+  }
+  if ((lines[index] ?? "").trim() === "---") index += 1;
+  const insertAt = trailing ? Math.min(index, lines.length - 1) : index;
+  lines.splice(insertAt, 0, line);
+  const next = bom + lines.join(eol);
+  const check = readArtifactVersion(next);
+  if (check.state !== "ok" || check.version !== version) return void 0;
+  return next;
+}
+async function planUpgrade(root) {
+  const artifacts = await collectVersionedArtifacts(root);
+  const pending = [];
+  const newer = [];
+  const unreadable = [];
+  for (const found of artifacts) {
+    const content = await readTextIfExists(found.path);
+    if (content === void 0) continue;
+    const state = readArtifactVersion(content);
+    if (state.state === "unreadable") {
+      unreadable.push({ ...found, reason: state.reason });
+      continue;
+    }
+    if (state.state === "ok") {
+      if (state.version > SCHEMA_VERSION) {
+        newer.push({ ...found, reason: `produce la versi\xF3n ${state.version}, m\xE1s nueva que la vigente (${SCHEMA_VERSION})` });
+        continue;
+      }
+      if (state.version === SCHEMA_VERSION) continue;
+    }
+    const from = state.state === "ok" ? state.version : 0;
+    const migration = SCHEMA_MIGRATIONS.find((m) => m.from === from);
+    if (!migration) {
+      unreadable.push({ ...found, reason: `no hay migraci\xF3n registrada desde la versi\xF3n ${from}` });
+      continue;
+    }
+    const stamped = stampSchemaVersion(content, migration.to);
+    if (stamped === void 0) {
+      unreadable.push({ ...found, reason: "no se pudo sellar con seguridad sin alterar el resto del contenido" });
+      continue;
+    }
+    pending.push({ ...found, from, to: migration.to, migration: migration.id, summary: migration.description });
+  }
+  return { root, currentVersion: SCHEMA_VERSION, pending, newer, unreadable, upToDate: pending.length === 0 };
+}
+async function removeDir(dir) {
+  try {
+    await fs2.rm(dir, { recursive: true, force: true });
+  } catch {
+  }
+}
+async function removeFile(file) {
+  try {
+    await fs2.rm(file, { force: true });
+  } catch {
+  }
+}
+function backupName(now) {
+  return `${localCompact(now)}${localOffset(now).replace(":", "")}`;
+}
+async function applyUpgrade(root, now = /* @__PURE__ */ new Date()) {
+  const plan = await planUpgrade(root);
+  if (plan.pending.length === 0) return { status: "up-to-date", plan, applied: [] };
+  const sddDir = path17.join(root, ".sdd");
+  const backupRoot = path17.join(sddDir, BACKUP_DIRNAME);
+  const name = backupName(now);
+  const backupDir = path17.join(backupRoot, name);
+  const pointerFile = path17.join(backupRoot, BACKUP_POINTER);
+  const previous = [];
+  try {
+    for (const item of plan.pending) {
+      const content = await readTextIfExists(item.path);
+      if (content === void 0) throw new Error("el elemento desapareci\xF3 mientras se respaldaba");
+      previous.push({ item, contents: content });
+      await writeText(path17.join(backupDir, "files", ...item.artifact.split("/")), content);
+    }
+    await writeText(
+      path17.join(backupDir, "backup.yaml"),
+      stringifyYaml5(
+        {
+          schema_version: SCHEMA_VERSION,
+          created_at: localStamp(now),
+          to_version: SCHEMA_VERSION,
+          files: plan.pending.map((i) => ({ artifact: i.artifact, from: i.from, to: i.to, migration: i.migration }))
+        },
+        { lineWidth: 120 }
+      )
+    );
+    await writeText(pointerFile, `${name}
+`);
+  } catch (err) {
+    await removeDir(backupDir);
+    await removeFile(pointerFile);
+    return { status: "failed", plan, applied: [], failure: { artifact: "(respaldo)", message: err.message } };
+  }
+  const written = [];
+  for (const { item, contents } of previous) {
+    try {
+      const next = stampSchemaVersion(contents, item.to);
+      if (next === void 0) throw new Error("no se pudo sellar con seguridad");
+      await writeText(item.path, next);
+      written.push(item);
+    } catch (err) {
+      for (const w of written) {
+        const prev = previous.find((p) => p.item.artifact === w.artifact);
+        if (prev) {
+          try {
+            await writeText(prev.item.path, prev.contents);
+          } catch {
+          }
+        }
+      }
+      await removeFile(pointerFile);
+      await removeDir(backupDir);
+      return { status: "failed", plan, applied: [], failure: { artifact: item.artifact, message: err.message } };
+    }
+  }
+  for (const dir of await listDirs(backupRoot)) {
+    if (dir !== name) await removeDir(path17.join(backupRoot, dir));
+  }
+  return {
+    status: "applied",
+    plan,
+    applied: written,
+    backup: {
+      name,
+      dir: backupDir,
+      relativeDir: toPosix(path17.relative(root, backupDir)),
+      createdAt: localStamp(now),
+      files: plan.pending.map((i) => i.artifact)
+    }
+  };
+}
+async function rollbackUpgrade(root) {
+  const sddDir = path17.join(root, ".sdd");
+  const backupRoot = path17.join(sddDir, BACKUP_DIRNAME);
+  const pointerFile = path17.join(backupRoot, BACKUP_POINTER);
+  const name = (await readTextIfExists(pointerFile))?.trim();
+  if (!name) return { status: "no-backup", restored: [] };
+  const backupDir = path17.join(backupRoot, name);
+  const manifestRaw = await readTextIfExists(path17.join(backupDir, "backup.yaml"));
+  if (manifestRaw === void 0) return { status: "no-backup", restored: [] };
+  let files = [];
+  try {
+    const parsed = parseYaml8(manifestRaw);
+    files = (parsed?.files ?? []).filter((f) => typeof f?.artifact === "string");
+  } catch {
+    return { status: "no-backup", restored: [] };
+  }
+  const restored = [];
+  for (const file of files) {
+    const from = path17.join(backupDir, "files", ...file.artifact.split("/"));
+    const to = path17.join(sddDir, ...file.artifact.split("/"));
+    const content = await readTextIfExists(from);
+    if (content === void 0) continue;
+    try {
+      await writeText(to, content);
+      restored.push(file.artifact);
+    } catch (err) {
+      return { status: "failed", restored, backup: name, failure: { artifact: file.artifact, message: err.message } };
+    }
+  }
+  await removeDir(backupDir);
+  await removeFile(pointerFile);
+  return { status: "restored", restored, backup: name };
+}
+async function upgradeAdvisory(root) {
+  const plan = await planUpgrade(root);
+  const diagnostics = [];
+  if (plan.pending.length > 0) {
+    diagnostics.push(
+      diag("ATLAS-UPGRADE-001", "warning", `El estado del proyecto no corresponde a la versi\xF3n vigente: ${plan.pending.length} elemento(s) por actualizar`, {
+        suggestion: "Vista previa: `satlas upgrade` \xB7 Aplicar: `satlas upgrade --apply`"
+      })
+    );
+  }
+  for (const item of plan.newer) {
+    diagnostics.push(
+      diag("ATLAS-UPGRADE-002", "warning", `El proyecto fue producido por una versi\xF3n m\xE1s nueva: "${item.artifact}" (${item.reason})`, {
+        path: item.path,
+        suggestion: "Actualiza la herramienta; no se actualiza hacia atr\xE1s"
+      })
+    );
+  }
+  for (const item of plan.unreadable) {
+    diagnostics.push(
+      diag("ATLAS-UPGRADE-003", "warning", `No se pudo interpretar "${item.artifact}": ${item.reason}`, {
+        path: item.path,
+        suggestion: "Revisa el elemento; no se modificar\xE1"
+      })
+    );
+  }
+  return { plan, diagnostics };
+}
+
+// src/sarif.ts
+import path18 from "path";
+var SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+var SARIF_VERSION = "2.1.0";
+var TOOL_NAME = "SpecAtlas";
+var TOOL_URL = "https://github.com/AlonsoAM/specatlas";
+var RULE_FAMILIES = [
+  [/^LINT-STR-/, "Estructura de los artefactos"],
+  [/^LINT-BIZ-/, "Lenguaje de negocio de la especificaci\xF3n"],
+  [/^LINT-DLT-/, "Delta de especificaci\xF3n"],
+  [/^LINT-EVD-/, "Evidencia registrada"],
+  [/^LINT-TSK-/, "Tareas declaradas"],
+  [/^LINT-PLN-/, "Plan t\xE9cnico"],
+  [/^(LINT-MKP|MKP)-/, "Mockups"],
+  [/^TRACE-/, "Trazabilidad requisito, escenario, tarea y evidencia"],
+  [/^PACK-/, "Pack de cumplimiento"],
+  [/^ATLAS-UPGRADE-/, "Actualizaci\xF3n del estado del proyecto"],
+  [/^ATLAS-ADAPTERS-/, "Adaptadores de agente"],
+  [/^ATLAS-CI-/, "Comprobaci\xF3n continua"],
+  [/^ATLAS-/, "Estado del proyecto"]
+];
+function ruleDescription(code) {
+  for (const [pattern, description] of RULE_FAMILIES) {
+    if (pattern.test(code)) return description;
+  }
+  return code;
+}
+function sarifLevel(severity) {
+  if (severity === "error") return "error";
+  if (severity === "warning") return "warning";
+  return "note";
+}
+function resultOf(diagnostic, root) {
+  const result = {
+    ruleId: diagnostic.code,
+    level: sarifLevel(diagnostic.severity),
+    message: { text: diagnostic.message }
+  };
+  if (diagnostic.path) {
+    const rel = path18.relative(root, diagnostic.path);
+    if (rel !== "") {
+      const physicalLocation = {
+        artifactLocation: { uri: toPosix(rel) },
+        ...diagnostic.line ? { region: { startLine: diagnostic.line } } : {}
+      };
+      result.locations = [{ physicalLocation }];
+    }
+  }
+  return result;
+}
+function toSarifReport(opts) {
+  const rules = /* @__PURE__ */ new Map();
+  const results = [];
+  for (const diagnostic of opts.diagnostics) {
+    let rule = rules.get(diagnostic.code);
+    if (!rule) {
+      rule = { id: diagnostic.code, shortDescription: { text: ruleDescription(diagnostic.code) } };
+      if (diagnostic.suggestion) rule.help = { text: diagnostic.suggestion };
+      rules.set(diagnostic.code, rule);
+    } else if (!rule.help && diagnostic.suggestion) {
+      rule.help = { text: diagnostic.suggestion };
+    }
+    results.push(resultOf(diagnostic, opts.root));
+  }
+  return {
+    $schema: SARIF_SCHEMA,
+    version: SARIF_VERSION,
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: TOOL_NAME,
+            informationUri: TOOL_URL,
+            version: opts.version,
+            rules: [...rules.values()]
+          }
+        },
+        results,
+        invocations: [{ executionSuccessful: !(opts.failed ?? false) }]
+      }
+    ]
+  };
+}
+function toSarifText(opts) {
+  return `${JSON.stringify(toSarifReport(opts), null, 2)}
+`;
+}
+
+// src/doctor.ts
+import path19 from "path";
 async function runDoctor(root) {
   const findings = [];
   const { workspace, config } = await loadWorkspace(root);
@@ -4160,7 +4513,7 @@ async function runDoctor(root) {
   const approvals = await loadApprovals(workspace.sddDir);
   findings.push(...approvals.diagnostics);
   for (const change of workspace.changes) {
-    const deltaPath = path17.join(change.dir, "spec.md");
+    const deltaPath = path19.join(change.dir, "spec.md");
     const deltaContent = await readTextIfExists(deltaPath);
     const approval = verifyApproval(change, approvals.byArtifact, config, deltaContent ?? void 0);
     if ((change.planPath || change.tasks) && (approval.status === "missing" || approval.status === "stale")) {
@@ -4182,7 +4535,7 @@ async function runDoctor(root) {
     }
     for (const override of change.meta?.overrides ?? []) {
       if (!override.reason.trim() || !override.by.trim()) {
-        findings.push(diag("ATLAS-LIFECYCLE-004", "error", `Override del gate "${override.gate}" sin motivo o autor`, { path: path17.join(change.dir, "meta.yaml") }));
+        findings.push(diag("ATLAS-LIFECYCLE-004", "error", `Override del gate "${override.gate}" sin motivo o autor`, { path: path19.join(change.dir, "meta.yaml") }));
       }
     }
   }
@@ -4205,7 +4558,7 @@ async function specHashOf(filePath) {
 }
 
 // src/gate.ts
-import path18 from "path";
+import path20 from "path";
 var UI_DOMAINS2 = /* @__PURE__ */ new Set(["frontend", "mobile", "fullstack"]);
 function count(name, diagnostics) {
   return {
@@ -4222,7 +4575,7 @@ function livingRequirementsMap(specs) {
   return map;
 }
 async function runCiGate(opts) {
-  const root = path18.resolve(opts.root);
+  const root = path20.resolve(opts.root);
   const { workspace, config } = await loadWorkspace(root);
   const diagnostics = [];
   const checks = [];
@@ -4233,7 +4586,7 @@ async function runCiGate(opts) {
   let changesErrors = 0;
   let changesWarnings = 0;
   for (const change of workspace.changes) {
-    const lintFindings = change.delta ? lintDelta(change.delta, living, path18.join(change.dir, "spec.md"), { language: config.spec.language }) : [];
+    const lintFindings = change.delta ? lintDelta(change.delta, living, path20.join(change.dir, "spec.md"), { language: config.spec.language }) : [];
     const trace = checkTrace({
       specs: workspace.specs,
       change,
@@ -4277,6 +4630,8 @@ async function runCiGate(opts) {
   return { checks, diagnostics, errors, warnings, failed };
 }
 export {
+  BACKUP_DIRNAME,
+  BACKUP_POINTER,
   BLOCK_HEAD_RE,
   BUILTIN_PACKS,
   CONFIG_FILE,
@@ -4286,14 +4641,21 @@ export {
   RULE_ID_RE,
   RULE_RE,
   RUN_EVENT_TYPES,
+  SARIF_SCHEMA,
+  SARIF_VERSION,
   SCENARIO_HEAD_RE,
   SCENARIO_ID_RE,
+  SCHEMA_MIGRATIONS,
+  SCHEMA_VERSION,
   SDD_DIR,
   SLUG_RE,
   TASK_ID_RE,
   TASK_LINE_RE,
+  TOOL_NAME,
+  TOOL_URL,
   adoptWorkspace,
   appendRunEvent,
+  applyUpgrade,
   approvalsSchema,
   approveFromGithub,
   archiveChange,
@@ -4308,6 +4670,7 @@ export {
   checkMockups,
   checkTrace,
   collectMetrics,
+  collectVersionedArtifacts,
   commentIssue,
   compareTaskIds,
   computeInputsHash,
@@ -4403,8 +4766,10 @@ export {
   patchChangeMeta,
   planBlock,
   planMockups,
+  planUpgrade,
   planWaves,
   profileSchema,
+  readArtifactVersion,
   readMockupManifest,
   readRun,
   readText,
@@ -4418,23 +4783,30 @@ export {
   renderTemplate,
   requiresMockups,
   resolvePacks,
+  rollbackUpgrade,
+  ruleDescription,
   runAnalyze,
   runCiGate,
   runDoctor,
   runProcess,
+  sarifLevel,
   setMockupRequirement,
   sha256,
   shortHash,
   signApproval,
   specHashOf,
   splitCommand,
+  stampSchemaVersion,
   stateLabel,
   syncGithubIssue,
   templatesFor,
   toPosix,
+  toSarifReport,
+  toSarifText,
   tokensFile,
   updateMockupScreenshots,
   updateRunStatus,
+  upgradeAdvisory,
   verifyApproval,
   walkFiles,
   writeConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specatlas/core",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Kernel determinista de SpecAtlas: parsing, validación, trazabilidad, olas y ciclo de vida",
   "license": "MIT",
   "type": "module",