HomeostasisJS

🚀 Control the Entropy of Your JavaScript Projects

HomeostasisJS is a linter specifically designed for the structure of your JavaScript projects. This tool enables you to define and enforce clear rules for organizing folders and files, ensuring that your project's growth remains consistent and maintainable.

As projects grow, it's common for their structure to become chaotic, leading to challenges such as:

• Difficulty locating files.
• High maintenance costs.
• Steep learning curves for new developers.

Why HomeostasisJS?

HomeostasisJS addresses these issues by allowing you to define project conventions early on and ensuring they are automatically enforced. This creates a system of negative feedback within your projects, reducing entropy and fostering a more structured and consistent architecture.

• 📁 Maintain Order: Avoid chaos as your codebase grows.
• ✅ Enforce Rules Automatically: Validate naming conventions, folder structures, and file formats without manual effort.
• 🌱 Scale with Confidence: Keep your project maintainable as your team or codebase expands.

By proactively managing your project’s structure, you can achieve a state of balance and organization—homeostasis—through consistent and enforceable rules.

How HomeostasisJS Works

1. Reads the descriptor.js file in the target folder.

2. Validates directories and files based on the rules defined in directories and files.

3. Executes registered plugins and triggers hooks during specific validation steps.

4. Generates logs or modifies the file structure as per the configuration.

5. Installs the library globally

npm install -g homeostasis

2. Create a Descriptor File:
   In each folder you want to manage, include a descriptor.js file containing the specific configuration for that folder. For example:

const config = {
  plugins: [],
  directories: {
    strict_content: false,
    purgeOnStrict: true,
    autoFormatting: true,
    convention: "kebab-case",
    ignore: ["dist"],
    content: [
      {
        name: "components",
        motivation:
          "Encapsulate reusable UI elements to promote modularity and consistency across the application",
      },
      {
        name: "services",
        motivation:
          "Handle business logic and external API interactions, ensuring a clean separation of concerns.",
      },
      {
        name: "repositories",
        motivation:
          "Manage data access and storage, acting as a bridge between the application and its data sources.",
      },
      {
        name: "utils",
        motivation:
          "Provide utility functions and helpers to streamline common operations and avoid code duplication.",
      },
    ],
  },
  files: {
    strict_content: false,
    purgeOnStrict: true,
    autoFormatting: true,
    removeIfFormatIsInvalid: true,
    content: [
      {
        name: "index.ts",
      },
      {
        name: "descriptor.js",
      },
    ],
    ignore: [],
    allowedFormats: [".ts", ".js"],
    convention: "kebab-case",
  },
};

module.exports = config;

• plugins: Plugins are customizable modules that allow you to extend and modify the default behavior of the library. Through events (hooks), plugins can intervene at different stages of the flow, such as validations, renaming, or handling conventions.
• directories: Rules for folders (strict or convention-based).
• files: Rules for files, including file limits and expected content.

Supported conventions: camel-case, snake-case, kebab-case, pascal-case.

3. Run Homeostasis

homeostasis ./path/to/your/project

Properties Table: directories and files

| Property | Type | Description | |---|---|---| | strict_content | boolean | Enforces strict validation of the directory or file structure. If enabled, only items listed in content are allowed. | | purgeOnStrict | boolean | If strict_content is enabled, removes all files or directories not listed in the content array. | | convention | string | Specifies the naming convention to enforce (e.g., kebab-case, snake-case, camel-case, pascal-case). | | ignore | string[] | A list of files or directories to be ignored during validation. | | autoFormatting | boolean | Automatically renames files or directories to comply with the naming convention. | | content | Array<{ name: string, motivation?: string }> | Specifies the required content. Each item is an object with a name and optional motivation. | | allowedFormats | string[] | (files property) A list of allowed file formats (e.g., [".ts", ".js", ".jsx"]). Files with extensions not included in this list will trigger hooks like onInvalidFormat and potentially onRemoveIfFormatIsInvalid. | | removeIfFormatIsInvalid | boolean | (files property) If set to true, files with invalid formats (not listed in allowedFormats) will be automatically removed. |

File-Specific Properties Table

| Property | Type | Description | |---|---|---| | allowedFormats | string[] | Specifies the allowed file extensions (e.g., [".ts", ".js"]). Files with extensions not included in this list will trigger hooks like onInvalidFormat and potentially onRemoveIfFormatIsInvalid. | | removeIfFormatIsInvalid | boolean | If enabled, removes files that do not match the allowed formats specified in allowedFormats. |

Plugins

Hooks Availables

| Hook | Description | |---|---| | onStrictContentValidation | Triggered during strict content validation to ensure files and directories meet defined rules. | | onPurgeOnStrict | Triggered when files or directories are removed because they do not comply with strict content rules. | | onInvalidConventionFilename | Triggered when a file does not conform to the naming convention specified in the configuration. | | onInvalidConventionInDescriptor | Triggered when the naming convention in the descriptor is invalid or does not comply with the rules. | | onInvalidConventionAndRename | Triggered when a file or directory is renamed to meet the specified naming convention. | | onIgnore | Triggered when a file or directory matches an item in the ignored list. | | onRemoveIfFormatIsInvalid | Triggered when a file is removed because its format is not allowed. | | onInvalidFormat | Triggered when a file has an invalid or unsupported format based on the configuration. | | onAutoFormatting | Triggered when automatic formatting is applied to file or directory names to meet naming conventions. |

Arguments Passed to Hooks

Each hook receives an args object that contains relevant data for the specific context of the event. Here's an example of common arguments:

| Argument | Description | |---|---| | currentType | The type of the current item being processed (e.g., "file" or "directory"). | | isDirectoryOrFile | Boolean indicating whether the item is a directory or a file. | | filteredMappedContent | Processed content of the directory or file. | | descriptorContent | The content of the descriptor.js configuration. | | ignoredFiles | An array of files or directories marked as ignored. | | conventionFormat | The naming convention being validated (e.g., "kebab-case"). | | formatFiles | The list of valid file formats allowed by the configuration. | | removeIfFormatIsInvalid | Boolean indicating whether invalid format files should be removed. | | originalName | The original name of the file or directory being renamed. | | newName | The new name applied after renaming to meet the convention. |

Plugin Example: StrictContentValidationPlugin

This example demonstrates a plugin that performs strict content validation and enforces naming conventions.

class StrictContentValidationPlugin {
  name = "StrictContentValidationPlugin";

  /**
   * Triggered during strict content validation.
   */
  onStrictContentValidation(args) {
    console.log(`[${this.name}] onStrictContentValidation triggered.`);
    console.log(`Args:`, args);
  }

  /**
   * Triggered when purging files or directories due to strict content rules.
   */
  onPurgeOnStrict(args) {
    console.log(`[${this.name}] onPurgeOnStrict triggered.`);
    console.log(`Args:`, args);
  }

  /**
   * Triggered when a file does not meet the naming convention.
   */
  onInvalidConventionFilename(args) {
    console.log(`[${this.name}] onInvalidConventionFilename triggered.`);
    console.log(`Args:`, args);
  }

  /**
   * Triggered when the descriptor file contains invalid conventions.
   */
  onInvalidConventionInDescriptor(args) {
    console.log(`[${this.name}] onInvalidConventionInDescriptor triggered.`);
    console.log(`Args:`, args);
  }

  /**
   * Triggered when renaming files or directories to meet the naming convention.
   */
  onInvalidConventionAndRename(args) {
    console.log(`[${this.name}] onInvalidConventionAndRename triggered.`);
    console.log(`Args:`, args);
  }

  /**
   * Triggered when a file or directory is ignored.
   */
  onIgnore(args) {
    console.log(`[${this.name}] onIgnore triggered.`);
    console.log(`Args:`, args);
  }

  /**
   * Triggered when a file format is invalid and is removed.
   */
  onRemoveIfFormatIsInvalid(args) {
    console.log(`[${this.name}] onRemoveIfFormatIsInvalid triggered.`);
    console.log(`Args:`, args);
  }

  /**
   * Triggered when a file format is invalid.
   */
  onInvalidFormat(args) {
    console.log(`[${this.name}] onInvalidFormat triggered.`);
    console.log(`Args:`, args);
  }

  /**
   * Triggered when auto-formatting is applied.
   */
  onAutoFormatting(args) {
    console.log(`[${this.name}] onAutoFormatting triggered.`);
    console.log(`Args:`, args);
  }
}

Plugin Implementation Example

This example demonstrates how to implement the StrictContentValidationPlugin in your configuration file.

const StrictContentValidationPlugin = require('./plugins/StrictContentValidationPlugin');

const config = {
  plugins: [
    new StrictContentValidationPlugin(),
  ],
  directories: {
    strict_content: true,
    purgeOnStrict: true,
    convention: "kebab-case",
    ignore: ["dist"],
    content: [
      { name: "components" },
      { name: "services" },
    ],
  },
  files: {
    allowedFormats: [".ts", ".js"],
    removeIfFormatIsInvalid: true,
  },
};

module.exports = config;