@eduardbar/drift 1.4.0 → 1.5.0

package/schemas/drift-guard.v1.json

@@ -0,0 +1,298 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "schemas/drift-guard.v1.json",
+  "title": "drift guard v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema",
+    "toolVersion",
+    "scannedAt",
+    "projectPath",
+    "mode",
+    "passed",
+    "metrics",
+    "checks",
+    "current"
+  ],
+  "properties": {
+    "$schema": {
+      "const": "schemas/drift-guard.v1.json"
+    },
+    "toolVersion": {
+      "type": "string"
+    },
+    "scannedAt": {
+      "type": "string"
+    },
+    "projectPath": {
+      "type": "string"
+    },
+    "mode": {
+      "enum": ["diff", "baseline"]
+    },
+    "passed": {
+      "type": "boolean"
+    },
+    "baseRef": {
+      "type": "string"
+    },
+    "baselinePath": {
+      "type": "string"
+    },
+    "metrics": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scoreDelta", "totalIssuesDelta", "severityDelta"],
+      "properties": {
+        "scoreDelta": { "type": "number" },
+        "totalIssuesDelta": { "type": "number" },
+        "severityDelta": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["error", "warning", "info"],
+          "properties": {
+            "error": { "type": "number" },
+            "warning": { "type": "number" },
+            "info": { "type": "number" }
+          }
+        }
+      }
+    },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "passed", "actual", "limit", "message"],
+        "properties": {
+          "id": { "type": "string" },
+          "passed": { "type": "boolean" },
+          "actual": { "type": "number" },
+          "limit": { "type": "number" },
+          "message": { "type": "string" }
+        }
+      }
+    },
+    "current": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "$schema",
+        "toolVersion",
+        "scannedAt",
+        "targetPath",
+        "files",
+        "totalIssues",
+        "totalScore",
+        "totalFiles",
+        "summary",
+        "quality",
+        "maintenanceRisk"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "schemas/drift-report.v1.json"
+        },
+        "toolVersion": {
+          "type": "string"
+        },
+        "scannedAt": {
+          "type": "string"
+        },
+        "targetPath": {
+          "type": "string"
+        },
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "issues", "score"],
+            "properties": {
+              "path": { "type": "string" },
+              "score": { "type": "number" },
+              "issues": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["rule", "severity", "message", "line", "column", "snippet"],
+                  "properties": {
+                    "rule": { "type": "string" },
+                    "severity": { "enum": ["error", "warning", "info"] },
+                    "message": { "type": "string" },
+                    "line": { "type": "number" },
+                    "column": { "type": "number" },
+                    "snippet": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "totalIssues": { "type": "number" },
+        "totalScore": { "type": "number" },
+        "totalFiles": { "type": "number" },
+        "summary": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["errors", "warnings", "infos", "byRule"],
+          "properties": {
+            "errors": { "type": "number" },
+            "warnings": { "type": "number" },
+            "infos": { "type": "number" },
+            "byRule": {
+              "type": "object",
+              "additionalProperties": { "type": "number" }
+            }
+          }
+        },
+        "quality": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["overall", "dimensions"],
+          "properties": {
+            "overall": { "type": "number" },
+            "dimensions": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["architecture", "complexity", "ai-patterns", "testing"],
+              "properties": {
+                "architecture": { "type": "number" },
+                "complexity": { "type": "number" },
+                "ai-patterns": { "type": "number" },
+                "testing": { "type": "number" }
+              }
+            }
+          }
+        },
+        "maintenanceRisk": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["score", "level", "hotspots", "signals"],
+          "properties": {
+            "score": { "type": "number" },
+            "level": { "enum": ["low", "medium", "high", "critical"] },
+            "hotspots": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "file",
+                  "driftScore",
+                  "complexityIssues",
+                  "hasNearbyTests",
+                  "changeFrequency",
+                  "risk",
+                  "reasons"
+                ],
+                "properties": {
+                  "file": { "type": "string" },
+                  "driftScore": { "type": "number" },
+                  "complexityIssues": { "type": "number" },
+                  "hasNearbyTests": { "type": "boolean" },
+                  "changeFrequency": { "type": "number" },
+                  "risk": { "type": "number" },
+                  "reasons": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                  }
+                }
+              }
+            },
+            "signals": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["highComplexityFiles", "filesWithoutNearbyTests", "frequentChangeFiles"],
+              "properties": {
+                "highComplexityFiles": { "type": "number" },
+                "filesWithoutNearbyTests": { "type": "number" },
+                "frequentChangeFiles": { "type": "number" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "diff": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "baseRef",
+        "projectPath",
+        "scannedAt",
+        "files",
+        "totalScoreBefore",
+        "totalScoreAfter",
+        "totalDelta",
+        "newIssuesCount",
+        "resolvedIssuesCount"
+      ],
+      "properties": {
+        "baseRef": { "type": "string" },
+        "projectPath": { "type": "string" },
+        "scannedAt": { "type": "string" },
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "path",
+              "scoreBefore",
+              "scoreAfter",
+              "scoreDelta",
+              "newIssues",
+              "resolvedIssues"
+            ],
+            "properties": {
+              "path": { "type": "string" },
+              "scoreBefore": { "type": "number" },
+              "scoreAfter": { "type": "number" },
+              "scoreDelta": { "type": "number" },
+              "newIssues": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["rule", "severity", "message", "line", "column", "snippet"],
+                  "properties": {
+                    "rule": { "type": "string" },
+                    "severity": { "enum": ["error", "warning", "info"] },
+                    "message": { "type": "string" },
+                    "line": { "type": "number" },
+                    "column": { "type": "number" },
+                    "snippet": { "type": "string" }
+                  }
+                }
+              },
+              "resolvedIssues": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["rule", "severity", "message", "line", "column", "snippet"],
+                  "properties": {
+                    "rule": { "type": "string" },
+                    "severity": { "enum": ["error", "warning", "info"] },
+                    "message": { "type": "string" },
+                    "line": { "type": "number" },
+                    "column": { "type": "number" },
+                    "snippet": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "totalScoreBefore": { "type": "number" },
+        "totalScoreAfter": { "type": "number" },
+        "totalDelta": { "type": "number" },
+        "newIssuesCount": { "type": "number" },
+        "resolvedIssuesCount": { "type": "number" }
+      }
+    }
+  }
+}

package/scripts/check-docs-drift.mjs

@@ -0,0 +1,154 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+function readRepoFile(rootDir, relativePath) {
+  return readFileSync(join(rootDir, relativePath), 'utf8')
+}
+
+function readPackageVersion(rootDir) {
+  const packageJson = JSON.parse(readRepoFile(rootDir, 'package.json'))
+  const version = packageJson?.version
+  if (typeof version !== 'string' || version.length === 0) {
+    throw new Error('package.json is missing a valid version field')
+  }
+  return version
+}
+
+function extractRuleIdsFromAnalyzer(analyzerContent) {
+  const blockMatch = analyzerContent.match(/export const RULE_WEIGHTS[\s\S]*?=\s*\{([\s\S]*?)\n\}/)
+  if (!blockMatch) {
+    throw new Error('Could not locate RULE_WEIGHTS block in src/analyzer.ts')
+  }
+
+  return Array.from(blockMatch[1].matchAll(/'([^']+)'\s*:/g), (match) => match[1])
+}
+
+function extractRuleIdsFromCatalog(catalogContent) {
+  const ids = []
+  for (const match of catalogContent.matchAll(/^\|\s*`([^`]+)`\s*\|/gm)) {
+    const id = match[1]
+    if (id !== 'id') {
+      ids.push(id)
+    }
+  }
+  return ids
+}
+
+function extractSingleNumber(content, pattern, errorMessage) {
+  const match = content.match(pattern)
+  if (!match) {
+    throw new Error(errorMessage)
+  }
+  return Number.parseInt(match[1], 10)
+}
+
+function extractAgentsVersion(agentsContent) {
+  const match = agentsContent.match(/Versi[oó]n del paquete:\s*`([^`]+)`/)
+  if (!match) {
+    throw new Error('AGENTS.md must include "Versión del paquete: `<version>`"')
+  }
+  return match[1]
+}
+
+function compareRuleSets(sourceRuleIds, catalogRuleIds) {
+  const sourceSet = new Set(sourceRuleIds)
+  const catalogSet = new Set(catalogRuleIds)
+
+  const missingInCatalog = [...sourceSet].filter((ruleId) => !catalogSet.has(ruleId)).sort()
+  const extraInCatalog = [...catalogSet].filter((ruleId) => !sourceSet.has(ruleId)).sort()
+
+  return { missingInCatalog, extraInCatalog }
+}
+
+export function validateDocsDrift(rootDir = process.cwd()) {
+  const packageVersion = readPackageVersion(rootDir)
+  const analyzer = readRepoFile(rootDir, 'src/analyzer.ts')
+  const rulesCatalog = readRepoFile(rootDir, 'docs/rules-catalog.md')
+  const readme = readRepoFile(rootDir, 'README.md')
+  const agents = readRepoFile(rootDir, 'AGENTS.md')
+
+  const sourceRuleIds = extractRuleIdsFromAnalyzer(analyzer)
+  const catalogRuleIds = extractRuleIdsFromCatalog(rulesCatalog)
+  const sourceRuleCount = sourceRuleIds.length
+
+  const readmeRuleCount = extractSingleNumber(
+    readme,
+    /defines\s+\*\*(\d+)\s+rule IDs\*\*/,
+    'README.md must declare the current rule ID count as "defines **<n> rule IDs**"',
+  )
+  const agentsRuleCount = extractSingleNumber(
+    agents,
+    /Estado actual:\s+\*\*(\d+)\s+rule IDs\*\*/,
+    'AGENTS.md must declare the current rule ID count as "Estado actual: **<n> rule IDs**"',
+  )
+  const catalogRuleCount = extractSingleNumber(
+    rulesCatalog,
+    /Total rule IDs currently defined:\s+\*\*(\d+)\*\*/,
+    'docs/rules-catalog.md must declare the current rule count line',
+  )
+  const agentsVersion = extractAgentsVersion(agents)
+  const { missingInCatalog, extraInCatalog } = compareRuleSets(sourceRuleIds, catalogRuleIds)
+
+  const errors = []
+
+  if (agentsVersion !== packageVersion) {
+    errors.push(`AGENTS.md package version (${agentsVersion}) does not match package.json (${packageVersion})`)
+  }
+
+  if (!rulesCatalog.includes('Source of truth: `RULE_WEIGHTS` in `src/analyzer.ts`.')) {
+    errors.push('docs/rules-catalog.md must explicitly declare RULE_WEIGHTS in src/analyzer.ts as source of truth')
+  }
+
+  if (catalogRuleIds.length !== sourceRuleCount) {
+    errors.push(`docs/rules-catalog.md table has ${catalogRuleIds.length} rule IDs, but RULE_WEIGHTS defines ${sourceRuleCount}`)
+  }
+
+  if (missingInCatalog.length > 0) {
+    errors.push(`rules missing in docs/rules-catalog.md: ${missingInCatalog.join(', ')}`)
+  }
+
+  if (extraInCatalog.length > 0) {
+    errors.push(`rules present in docs/rules-catalog.md but not in RULE_WEIGHTS: ${extraInCatalog.join(', ')}`)
+  }
+
+  if (readmeRuleCount !== sourceRuleCount) {
+    errors.push(`README.md rule ID count (${readmeRuleCount}) does not match RULE_WEIGHTS (${sourceRuleCount})`)
+  }
+
+  if (agentsRuleCount !== sourceRuleCount) {
+    errors.push(`AGENTS.md rule ID count (${agentsRuleCount}) does not match RULE_WEIGHTS (${sourceRuleCount})`)
+  }
+
+  if (catalogRuleCount !== sourceRuleCount) {
+    errors.push(`docs/rules-catalog.md total rule ID count (${catalogRuleCount}) does not match RULE_WEIGHTS (${sourceRuleCount})`)
+  }
+
+  return {
+    ok: errors.length === 0,
+    packageVersion,
+    sourceRuleCount,
+    errors,
+  }
+}
+
+export function runDocsDriftCheck(rootDir = process.cwd()) {
+  const result = validateDocsDrift(rootDir)
+
+  if (!result.ok) {
+    process.stderr.write('Docs drift check failed:\n')
+    for (const error of result.errors) {
+      process.stderr.write(`- ${error}\n`)
+    }
+    process.exitCode = 1
+    return
+  }
+
+  process.stdout.write(
+    `Docs drift check passed: package version ${result.packageVersion}, rule IDs ${result.sourceRuleCount}, docs aligned.\n`,
+  )
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runDocsDriftCheck()
+}