Parser DSL YAML · FARO-ENG-002

{
  "name": "@faro/rule-parser",
  "version": "1.0.0",
  "description": "FARO Connect YAML DSL Rule Parser",
  "type": "module",
  "scripts": {
    "dev": "tsx src/cli.ts",
    "validate": "tsx src/cli.ts validate --path ./rules/mvp",
    "import": "tsx src/cli.ts import --path ./rules/mvp",
    "test:rules": "tsx src/cli.ts test --path ./rules/mvp",
    "list": "tsx src/cli.ts list",
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  },
  "dependencies": {
    "ajv": "^8.17.1",
    "ajv-formats": "^3.0.1",
    "commander": "^12.1.0",
    "dotenv": "^16.4.5",
    "glob": "^11.0.0",
    "pg": "^8.13.1",
    "yaml": "^2.6.1",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "@types/node": "^22.10.0",
    "@types/pg": "^8.11.10",
    "tsx": "^4.19.2",
    "typescript": "^5.7.2",
    "vitest": "^2.1.8"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "outDir": "dist",
    "rootDir": ".",
    "types": ["node"]
  },
  "include": ["src/**/*.ts", "tests/**/*.ts"]
}

# Conexión PostgreSQL al schema faro
DATABASE_URL=postgresql://faro_app:password@localhost:5432/faro

# Carpeta raíz de reglas YAML
FARO_RULES_PATH=./rules/mvp

# Modo de import: dry-run (no escribe DB) o write
FARO_IMPORT_MODE=dry-run

# Empresa target por defecto (UUID o vacío para global)
FARO_DEFAULT_COMPANY_ID=

# Modo strict: aborta también en warnings
FARO_STRICT_MODE=true

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "FARO Rule Schema MVP",
  "type": "object",
  "additionalProperties": true,
  "required": [
    "rule_code", "tension_code", "version", "status",
    "name", "description", "scope", "data_requirements",
    "conditions", "severity", "output", "tests"
  ],
  "properties": {
    "rule_code": { "type": "string", "pattern": "^RULE-TNS-[0-9]{3}$" },
    "tension_code": { "type": "string", "pattern": "^TNS-[0-9]{3}$" },
    "version": { "type": "integer", "minimum": 1 },
    "status": {
      "type": "string",
      "enum": ["draft", "active", "inactive", "archived"]
    },
    "name": { "type": "string", "minLength": 3 },
    "description": { "type": "string", "minLength": 10 },

    "scope": {
      "type": "object",
      "required": ["company_types", "modules", "frequency", "evaluation_window"],
      "properties": {
        "company_types": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
        "modules": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
        "frequency": {
          "type": "string",
          "enum": ["daily", "weekly", "monthly", "quarterly", "annual", "on_demand"]
        },
        "evaluation_window": { "type": "string" },
        "comparison_window": { "type": "string" },
        "dimension": { "type": "string" }
      }
    },

    "data_requirements": {
      "type": "object",
      "required": [
        "required_kpis", "minimum_confidence_score",
        "missing_data_policy", "stale_data_policy"
      ],
      "properties": {
        "required_kpis": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
        "minimum_confidence_score": { "type": "number", "minimum": 0, "maximum": 100 },
        "missing_data_policy": {
          "type": "string",
          "enum": [
            "do_not_trigger", "trigger_with_warning",
            "create_data_quality_tension", "use_last_available",
            "manual_review"
          ]
        },
        "stale_data_policy": {
          "type": "string",
          "enum": ["warn", "do_not_trigger", "use_last_available"]
        }
      }
    },

    "conditions": {
      "type": "object",
      "minProperties": 1,
      "properties": {
        "all": { "type": "array", "items": { "$ref": "#/$defs/condition" } },
        "any": { "type": "array", "items": { "$ref": "#/$defs/condition" } },
        "none": { "type": "array", "items": { "$ref": "#/$defs/condition" } }
      }
    },

    "severity": {
      "type": "object",
      "required": ["default"],
      "properties": {
        "default": {
          "type": "string",
          "enum": ["low", "medium", "high", "critical"]
        },
        "escalation": { "type": "array" }
      }
    },

    "output": {
      "type": "object",
      "required": [
        "create_tension", "title", "diagnosis_template",
        "recommended_actions", "assign_to_role",
        "evidence_required", "default_sla_days", "score_impact"
      ],
      "properties": {
        "create_tension": { "type": "boolean" },
        "title": { "type": "string" },
        "diagnosis_template": { "type": "string" },
        "recommended_actions": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
        "assign_to_role": { "type": "string" },
        "approver_role": { "type": "string" },
        "evidence_required": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
        "default_sla_days": { "type": "integer", "minimum": 1 },
        "score_impact": {
          "type": "object",
          "required": ["base"],
          "properties": {
            "base": { "type": "number" },
            "max": { "type": "number" }
          }
        }
      }
    },

    "tests": { "type": "array", "minItems": 1 }
  },

  "$defs": {
    "condition": {
      "type": "object",
      "required": ["kpi", "metric", "operator"],
      "properties": {
        "kpi": { "type": "string" },
        "metric": { "type": "string" },
        "operator": {
          "type": "string",
          "enum": [
            ">", ">=", "<", "<=", "==", "!=",
            "between", "in", "not_in",
            "exists", "missing",
            "changed_by_pct", "older_than_days"
          ]
        },
        "value": {}
      }
    }
  }
}

import type { FaroRule } from "../types/rule.types.js";
import type { ValidationResult, ValidationIssue } from "../types/validation.types.js";
import { validateSchema } from "./validateSchema.js";
import { validateOperators } from "./validateOperators.js";
import { validateKpis } from "./validateKpis.js";
import { validateActions } from "./validateActions.js";
import { validateRoles } from "./validateRoles.js";
import { validateEvidence } from "./validateEvidence.js";
import { validateTests } from "./validateTests.js";
import { validateSecurity } from "./validateSecurity.js";

export function validateRule(rule: unknown): ValidationResult {
  const issues: ValidationIssue[] = [];

  const schemaResult = validateSchema(rule);
  issues.push(...schemaResult.issues);
  if (!schemaResult.valid) return { valid: false, issues };

  const typedRule = rule as FaroRule;
  const validators = [
    validateOperators, validateKpis, validateActions, validateRoles,
    validateEvidence, validateTests, validateSecurity
  ];
  for (const validator of validators) {
    issues.push(...validator(typedRule).issues);
  }

  return { valid: !issues.some((i) => i.severity === "error"), issues };
}

#!/usr/bin/env node
import { Command } from "commander";
import dotenv from "dotenv";
import { validateCommand } from "./commands/validateCommand.js";
import { importCommand } from "./commands/importCommand.js";
import { testCommand } from "./commands/testCommand.js";

dotenv.config();
const program = new Command();

program
  .name("faro-rule-parser")
  .description("FARO Connect YAML DSL Rule Parser")
  .version("1.0.0");

program.command("validate")
  .description("Validate YAML rules")
  .requiredOption("--path <path>", "Path to YAML rules")
  .action(async (options) => { await validateCommand(options.path); });

program.command("import")
  .description("Import YAML rules into database")
  .requiredOption("--path <path>", "Path to YAML rules")
  .option("--company-id <companyId>", "Company ID for company-specific rules")
  .option("--dry-run", "Validate without importing", false)
  .action(async (options) => {
    await importCommand({
      path: options.path,
      companyId: options.companyId ?? null,
      dryRun: options.dryRun
    });
  });

program.command("test")
  .description("Run declarative tests embedded in YAML rules")
  .requiredOption("--path <path>", "Path to YAML rules")
  .action(async (options) => { await testCommand(options.path); });

program.parseAsync(process.argv);

import type pg from "pg";
import type { NormalizedRule } from "../types/validation.types.js";

export async function upsertRuleDefinition(
  client: pg.PoolClient,
  params: { companyId: string | null; rule: NormalizedRule }
): Promise<void> {
  const { companyId, rule } = params;

  await client.query(
    `
    INSERT INTO faro.rule_definitions (
      company_id, rule_code, name, description,
      rule_type, rule_format, rule_body,
      severity_default, is_mvp, status, version
    )
    VALUES (
      $1, $2, $3, $4,
      'tension', 'yaml', $5::jsonb,
      $6, $7, $8, $9
    )
    ON CONFLICT (company_id, rule_code, version)
    DO UPDATE SET
      name = EXCLUDED.name,
      description = EXCLUDED.description,
      rule_body = EXCLUDED.rule_body,
      severity_default = EXCLUDED.severity_default,
      is_mvp = EXCLUDED.is_mvp,
      status = EXCLUDED.status,
      updated_at = now()
    `,
    [
      companyId, rule.ruleCode, rule.name, rule.description,
      JSON.stringify(rule.ruleBody),
      rule.severityDefault, rule.isMvp, rule.status, rule.version
    ]
  );
}

import pg from "pg";
import dotenv from "dotenv";

dotenv.config();
const { Pool } = pg;

if (!process.env.DATABASE_URL) {
  throw new Error("DATABASE_URL is required");
}

export const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export async function withDbContext<T>(
  companyId: string | null,
  userId: string | null,
  roleCodes: string[],
  fn: (client: pg.PoolClient) => Promise<T>
): Promise<T> {
  const client = await pool.connect();
  try {
    await client.query("BEGIN");
    if (companyId) {
      await client.query(`SELECT set_config('app.company_id', $1, true)`, [companyId]);
    }
    if (userId) {
      await client.query(`SELECT set_config('app.user_id', $1, true)`, [userId]);
    }
    await client.query(`SELECT set_config('app.role_codes', $1, true)`, [roleCodes.join(",")]);

    const result = await fn(client);
    await client.query("COMMIT");
    return result;
  } catch (error) {
    await client.query("ROLLBACK");
    throw error;
  } finally {
    client.release();
  }
}

name: Validate FARO Rules

on:
  pull_request:
    paths:
      - "rules/**/*.yaml"
      - "rules/**/*.yml"
      - "src/**"

jobs:
  validate-rules:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm run typecheck
      - run: npm run validate
      - run: npm run test:rules