@specatlas/core 0.1.26 → 0.1.28

package/dist/index.d.ts

@@ -44,8 +44,41 @@ interface Scenario {
     reqId: string;
     when: string[];
     then: string[];
+    contracts?: string[];
     line: number;
 }
+type ContractFormat = 'openapi' | 'graphql' | 'protobuf' | 'unsupported';
+interface ContractOperation {
+    id: string;
+    kind: ContractFormat;
+    file: string;
+    line: number;
+}
+interface ContractFile {
+    path: string;
+    format: ContractFormat;
+    operations: ContractOperation[];
+}
+interface ContractsState {
+    files: ContractFile[];
+    operations: ContractOperation[];
+    findings: Diagnostic[];
+}
+interface LinkEntry {
+    name: string;
+    path: string;
+}
+interface LinkStatus extends LinkEntry {
+    available: boolean;
+    requirements: number;
+    domains: string[];
+    error?: string;
+}
+interface LinksState {
+    entries: LinkStatus[];
+    specs: SpecRef[];
+    unavailable: string[];
+}
 interface Requirement {
     id: string;
     title: string;
@@ -195,6 +228,17 @@ interface MockupManifest {
     tokens?: string;
     screens: MockupScreen[];
 }
+interface ClarifyItem {
+    text: string;
+    line: number;
+    answer?: string;
+}
+interface ClarifyFile {
+    path: string;
+    open: ClarifyItem[];
+    resolved: ClarifyItem[];
+    diagnostics: Diagnostic[];
+}
 interface Change {
     slug: string;
     dir: string;
@@ -204,6 +248,10 @@ interface Change {
     verify?: VerifyFile;
     fix?: VerifyFile;
     fixCovers?: string[];
+    clarify?: ClarifyFile;
+    clarifyPath?: string;
+    docsPaths?: string[];
+    contracts?: ContractsState;
     planPath?: string;
     reviewPath?: string;
     presentationPath?: string;
@@ -220,7 +268,8 @@ interface Workspace {
     sddDir: string;
     specs: SpecRef[];
     changes: Change[];
-    archived?: Change[];
+    archived: Change[];
+    links?: LinksState;
     diagnostics: Diagnostic[];
 }
 
@@ -295,6 +344,27 @@ declare const atlasConfigSchema: z.ZodObject<{
         }, {
             mode?: "off" | "advisory" | "blocking" | undefined;
         }>>;
+        clarify: z.ZodDefault<z.ZodObject<{
+            mode: z.ZodDefault<z.ZodEnum<["off", "advisory", "blocking"]>>;
+        }, "strip", z.ZodTypeAny, {
+            mode: "off" | "advisory" | "blocking";
+        }, {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        }>>;
+        docs: z.ZodDefault<z.ZodObject<{
+            mode: z.ZodDefault<z.ZodEnum<["off", "advisory", "blocking"]>>;
+        }, "strip", z.ZodTypeAny, {
+            mode: "off" | "advisory" | "blocking";
+        }, {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        }>>;
+        contracts: z.ZodDefault<z.ZodObject<{
+            mode: z.ZodDefault<z.ZodEnum<["off", "advisory", "blocking"]>>;
+        }, "strip", z.ZodTypeAny, {
+            mode: "off" | "advisory" | "blocking";
+        }, {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        }>>;
         mockup: z.ZodDefault<z.ZodObject<{
             require_approval: z.ZodDefault<z.ZodBoolean>;
             compare_in_verify: z.ZodDefault<z.ZodBoolean>;
@@ -319,6 +389,15 @@ declare const atlasConfigSchema: z.ZodObject<{
         review: {
             mode: "off" | "advisory" | "blocking";
         };
+        clarify: {
+            mode: "off" | "advisory" | "blocking";
+        };
+        docs: {
+            mode: "off" | "advisory" | "blocking";
+        };
+        contracts: {
+            mode: "off" | "advisory" | "blocking";
+        };
         mockup: {
             require_approval: boolean;
             compare_in_verify: boolean;
@@ -337,6 +416,15 @@ declare const atlasConfigSchema: z.ZodObject<{
         review?: {
             mode?: "off" | "advisory" | "blocking" | undefined;
         } | undefined;
+        clarify?: {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        } | undefined;
+        docs?: {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        } | undefined;
+        contracts?: {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        } | undefined;
         mockup?: {
             require_approval?: boolean | undefined;
             compare_in_verify?: boolean | undefined;
@@ -452,6 +540,15 @@ declare const atlasConfigSchema: z.ZodObject<{
         review: {
             mode: "off" | "advisory" | "blocking";
         };
+        clarify: {
+            mode: "off" | "advisory" | "blocking";
+        };
+        docs: {
+            mode: "off" | "advisory" | "blocking";
+        };
+        contracts: {
+            mode: "off" | "advisory" | "blocking";
+        };
         mockup: {
             require_approval: boolean;
             compare_in_verify: boolean;
@@ -515,6 +612,15 @@ declare const atlasConfigSchema: z.ZodObject<{
         review?: {
             mode?: "off" | "advisory" | "blocking" | undefined;
         } | undefined;
+        clarify?: {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        } | undefined;
+        docs?: {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        } | undefined;
+        contracts?: {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        } | undefined;
         mockup?: {
             require_approval?: boolean | undefined;
             compare_in_verify?: boolean | undefined;
@@ -803,6 +909,8 @@ declare function parseApprovals(raw: string, filePath: string): {
     diagnostics: Diagnostic[];
 };
 
+declare function parseClarify(content: string, filePath: string): ClarifyFile;
+
 interface GlossaryTerm {
     term: string;
     definition: string;
@@ -830,6 +938,8 @@ interface ImpactReport {
     target: string;
     kind: 'requirement' | 'file';
     exists: boolean;
+    external?: boolean;
+    origin?: string;
     scenarios: string[];
     tasks: ImpactTask[];
     requirements: string[];
@@ -880,6 +990,10 @@ interface TraceInput {
     specs: SpecRef[];
     change: Change;
     requireEvidence: boolean;
+    linked?: {
+        ids: string[];
+        unavailable: string[];
+    };
 }
 declare function buildTraceGraph(input: TraceInput): TraceGraph;
 declare function checkTrace(input: TraceInput): TraceResult;
@@ -910,7 +1024,7 @@ declare function planWaves(tasks: TasksFile, opts?: {
 }): WavePlan;
 declare function planBlock(block: TaskBlock, maxParallel: number): BlockWavePlan;
 
-type ChangeState = 'draft' | 'spec_draft' | 'awaiting_mockups' | 'awaiting_approval' | 'approved' | 'planned' | 'building' | 'built' | 'verified' | 'ready' | 'archived';
+type ChangeState = 'draft' | 'spec_draft' | 'awaiting_mockups' | 'awaiting_approval' | 'approved' | 'planned' | 'building' | 'built' | 'verified' | 'reviewed' | 'ready' | 'archived';
 interface NextAction {
     command: string;
     description: string;
@@ -946,6 +1060,9 @@ interface DeriveInput {
     specContent?: string;
 }
 declare function requiresMockups(meta: ChangeMeta | undefined, cfg: AtlasConfig): boolean;
+declare function docsReady(change: Change): boolean;
+declare function clarifyAdvisory(change: Change, cfg: AtlasConfig): Diagnostic[];
+declare function docsAdvisory(change: Change, cfg: AtlasConfig): Diagnostic[];
 declare function deriveState(input: DeriveInput): DerivedState;
 declare function stateLabel(state: ChangeState): string;
 
@@ -1125,6 +1242,8 @@ interface TemplateSet {
     tasks: string;
     verify: string;
     fix: string;
+    docTecnica: string;
+    docManual: string;
 }
 declare function templatesFor(language: Language): TemplateSet;
 declare function renderTemplate(template: string, vars: Record<string, string>): string;
@@ -1829,6 +1948,61 @@ interface WriteLivingFixResult {
 }
 declare function writeLivingFix(root: string, input: WriteLivingFixInput): Promise<WriteLivingFixResult>;
 
+declare const CONTRACTS_DIR = "contracts";
+declare function formatOf(file: string, content: string): ContractFormat;
+declare function parseContract(file: string, content: string): ContractFile & {
+    findings: Diagnostic[];
+};
+declare function loadContracts(changeDir: string): Promise<ContractsState>;
+declare function contractCoverage(change: Change, mode: AtlasConfig['gates']['contracts']['mode']): Diagnostic[];
+declare function contractsAdvisory(change: Change, cfg: AtlasConfig): Diagnostic[];
+
+declare const LINKS_FILE = "links.yaml";
+declare function resolveLinkPath(root: string, linkPath: string): string;
+declare function loadLinks(root: string): Promise<LinksState>;
+interface AddLinkResult {
+    entry?: LinkEntry;
+    diagnostics: Diagnostic[];
+}
+declare function addLink(root: string, opts: {
+    path: string;
+    name?: string;
+}): Promise<AddLinkResult>;
+interface RemoveLinkResult {
+    removed?: string;
+    diagnostics: Diagnostic[];
+}
+declare function removeLink(root: string, ref: string): Promise<RemoveLinkResult>;
+declare function linkedRequirementIds(state: LinksState | undefined): string[];
+declare function linkedTraceInput(workspace: {
+    links?: LinksState;
+}): {
+    ids: string[];
+    unavailable: string[];
+} | undefined;
+declare function ensureLinksFile(root: string): Promise<void>;
+
+type DocsTipo = 'tecnica' | 'manual' | 'all';
+declare const DOCS_MARKER_START = "<!-- specatlas:generado:inicio -->";
+declare const DOCS_MARKER_END = "<!-- specatlas:generado:fin -->";
+interface GenerateDocsOptions {
+    root: string;
+    slug: string;
+    tipo?: DocsTipo;
+    now?: Date;
+}
+interface GeneratedDoc {
+    tipo: 'tecnica' | 'manual';
+    path: string;
+    created: boolean;
+}
+interface GenerateDocsResult {
+    slug: string;
+    files: GeneratedDoc[];
+    diagnostics: Diagnostic[];
+}
+declare function generateDocs(opts: GenerateDocsOptions): Promise<GenerateDocsResult>;
+
 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";
@@ -1928,4 +2102,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, 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, LIVING_FIXES_DIR, type Lane, type Language, type LinkedIssue, type LintOptions, type LivingFix, 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, type WriteLivingFixInput, type WriteLivingFixResult, 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, loadLivingFixes, loadProfileFile, loadProfilesFromDir, loadProjectPacks, loadSpecs, loadWorkspace, localCompact, localDate, localMonth, localOffset, localStamp, matchGlob, mockupManifestSchema, mockupsDir, mockupsReady, moveDirectory, packFindings, parseApprovals, parseChangeMeta, parseConfig, parseDelta, parseFixCovers, parseFrontmatter, parseGitHubRemote, parseGlossary, parseIssueUrl, parseLivingFix, 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, writeLivingFix, writeMockupManifest, writeMockupPlan, writeText };
+export { type AddLinkResult, 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, CONTRACTS_DIR, CORE_VERSION, type CaptureResult, type Change, type ChangeMeta, type ChangeMetrics, type ChangeState, type CiCheck, type CiExtraCheck, type CiOptions, type CiResult, type ClarifyFile, type ClarifyItem, type ContractFile, type ContractFormat, type ContractOperation, type ContractsState, DOCS_MARKER_END, DOCS_MARKER_START, type Delta, type DeltaOp, type DeriveInput, type DerivedState, type DetectionResult, type Diagnostic, type DocsTipo, type DoctorReport, type Domain, type Evidence, type EvidenceMethod, type EvidenceResult, type ExecOptions, type ExecResult, type FoldOutcome, type FrontmatterResult, type GenerateDocsOptions, type GenerateDocsResult, type GeneratedDoc, type GhRunner, type GitHubRepo, type GlossaryTerm, type ImpactEvidence, type ImpactReport, type ImpactTask, type InitOptions, type InitResult, type IssueBodyInput, LINKS_FILE, LIVING_FIXES_DIR, type Lane, type Language, type LinkEntry, type LinkStatus, type LinkedIssue, type LinksState, type LintOptions, type LivingFix, 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 RemoveLinkResult, 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, type WriteLivingFixInput, type WriteLivingFixResult, addLink, adoptWorkspace, appendRunEvent, applyUpgrade, approvalsSchema, approveFromGithub, archiveChange, artifactHash, atlasConfigSchema, buildTraceGraph, canonicalizeMarkdown, captureMockups, changeMarker, changeMetaSchema, changeMetaYaml, checkMockups, checkTrace, clarifyAdvisory, collectMetrics, collectVersionedArtifacts, commentIssue, compareTaskIds, computeInputsHash, configToYaml, contractCoverage, contractsAdvisory, copyFile, countBySeverity, createChange, createIssue, createRun, defaultConfig, deriveState, detectProfiles, detectRepo, detectionToYaml, diag, docsAdvisory, docsReady, editIssue, emitFrontmatter, ensureDir, ensureLinksFile, ensureSddDirs, esc, evaluatePacks, evidenceSummary, exists, findLinkedIssue, findWorkspaceRoot, firstToken, foldDelta, formatOf, generateDocs, generatePresentation, generateRunId, getNumber, getString, ghAuthStatus, ghAvailable, hasErrors, hasShellMetacharacters, impactOfFile, impactOfRequirement, indexMarkdown, initWorkspace, inline, isCommandAllowed, isDirectory, issueBody, issueLabels, laneOrDefault, linkedRequirementIds, linkedTraceInput, lintDelta, lintMockupHtml, lintMockupManifest, lintPlan, lintRequirement, lintSpec, lintTasks, lintVerify, listChangeSlugs, listDir, listDirs, listRuns, livingRequirementsMap, loadActiveProfile, loadApprovals, loadChange, loadConfig, loadContracts, loadDetectedBest, loadLinks, loadLivingFixes, loadProfileFile, loadProfilesFromDir, loadProjectPacks, loadSpecs, loadWorkspace, localCompact, localDate, localMonth, localOffset, localStamp, matchGlob, mockupManifestSchema, mockupsDir, mockupsReady, moveDirectory, packFindings, parseApprovals, parseChangeMeta, parseClarify, parseConfig, parseContract, parseDelta, parseFixCovers, parseFrontmatter, parseGitHubRemote, parseGlossary, parseIssueUrl, parseLivingFix, parseRequirementBlocks, parseSpecFile, parseTasksFile, parseVerifyFile, patchChangeMeta, planBlock, planMockups, planUpgrade, planWaves, profileSchema, readArtifactVersion, readMockupManifest, readRun, readText, readTextIfExists, recordEvidence, regenerateIndex, removeLink, renderMarkdown, renderRequirement, renderTemplate, requiresMockups, resolveLinkPath, 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, writeLivingFix, writeMockupManifest, writeMockupPlan, writeText };