Programmatic API

Import Functions

Use FS Guard programmatically in your Node.js scripts or tools:

typescript

import { validate, fsGuard, loadConfig, resolvePreset } from "@promise-inc/fs-guard";

validate()

Main validation function. Accepts a config object and returns validation results:

typescript

import { validate } from "@promise-inc/fs-guard";

const result = await validate({
  rules: {
    "src": "*",
    "src/components": ["index.ts"],
  },
});

if (!result.valid) {
  console.error("Validation failed:");
  result.violations.forEach(v => {
    console.error(`  ${v.path}: ${v.message}`);
  });
  process.exit(1);
}

fsGuard()

Alias for validate(). Same functionality:

typescript

import { fsGuard } from "@promise-inc/fs-guard";

const result = await fsGuard({
  preset: "react-ts",
  rules: {
    "src/features": "*",
  },
});

loadConfig()

Load configuration from file. Searches standard locations:

typescript

import { loadConfig } from "@promise-inc/fs-guard";

// Load from default locations
const config = await loadConfig();

// Load from specific path
const config = await loadConfig("./custom-config.ts");

resolvePreset()

Resolve a preset name to its configuration:

typescript

import { resolvePreset } from "@promise-inc/fs-guard";

const nestjsConfig = resolvePreset("nestjs");
const reactConfig = resolvePreset("react-ts");

// Merge with custom rules
const customConfig = {
  ...reactConfig,
  rules: {
    ...reactConfig.rules,
    "src/custom": "*",
  },
};

ValidationResult

Result object returned by validate():

typescript

interface ValidationResult {
  valid: boolean;
  violations: Violation[];
}

Violation

Individual validation failure:

typescript

interface Violation {
  path: string;
  message: string;
  rule: string;
  type: "missing-directory" | "missing-file" | "pattern-mismatch" | "max-depth-exceeded";
}

Complete Example

typescript

import { validate, loadConfig, resolvePreset } from "@promise-inc/fs-guard";

async function validateProject() {
  // Option 1: Load from config file
  const config = await loadConfig();

  // Option 2: Use preset
  const config = resolvePreset("nestjs");

  // Option 3: Define inline
  const config = {
    rules: {
      "src": "*",
      "src/modules": {
        required: true,
        pattern: "*.module.ts",
      },
    },
  };

  // Validate
  const result = await validate(config);

  if (!result.valid) {
    console.error(`❌ Found ${result.violations.length} violations:`);
    result.violations.forEach(v => {
      console.error(`  ${v.path}`);
      console.error(`    ✗ ${v.message}`);
    });
    process.exit(1);
  }

  console.log("✓ All validations passed!");
}

validateProject();

CLI Reference