How to Set Up Absolute Imports with the Constitution's Import Rules in aios-core

Configure the @/ alias in tsconfig.json to map to ./.aios-core/core, update Jest's moduleNameMapper to resolve the alias during testing, and enable the ESLint Constitution gate to enforce absolute imports over deep relative paths.

The SynkraAI/aios-core repository enforces strict coding standards through its AIOS Constitution, which mandates absolute imports with the Constitution's import rules in aios-core to maintain architectural consistency. This approach eliminates fragile relative path chains and ensures modules remain decoupled during refactoring.

Understanding the AIOS Constitution's Import Philosophy

The Absolute Import Mandate

According to .aios-core/constitution.md (lines 106-114), the Constitution declares that code SHOULD prefer absolute imports using the @/ alias. This rule is categorized as a "SHOULD" rather than "MUST," meaning it is strongly recommended and enforced by tooling but allows rare exceptions for intra-feature imports within the same logical boundary.

Why Relative Imports Are Discouraged

Deep relative imports such as ../../../stores/feature/store create fragile dependencies that break when files are moved or reorganized. The Constitution explicitly discourages these patterns because they couple modules to specific directory structures rather than logical boundaries, violating the principle of decoupling that underpins the aios-core architecture.

Configuring TypeScript Path Aliases

To enable the @/ alias throughout the repository, the tsconfig.json file defines a paths mapping that resolves @/ to the core source directory:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./.aios-core/core/*"]
    }
  }
}

This configuration (found at lines 21-25 in tsconfig.json) instructs the TypeScript compiler to treat any import starting with @/ as relative to the ./.aios-core/core directory, establishing the foundation for absolute imports with the Constitution's import rules in aios-core.

Configuring Jest to Resolve Absolute Imports

Test runners require separate configuration to understand the @/ alias. In .aios-core/development/templates/service-template/jest.config.js (lines 75-78), the moduleNameMapper setting translates the alias during test execution:

module.exports = {
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/$1'
  }
};

This regex pattern captures any module path starting with @/ and remaps it to the project root, ensuring that tests resolve the same modules as the production build and maintaining consistency across the testing pipeline.

Enforcing Import Rules with ESLint

The repository includes a custom ESLint rule as part of the "Constitution gate" that warns developers when relative imports (../../../) are used where absolute ones are possible. While this gate is non-blocking during development, it reports violations to maintain code quality standards. Keeping this rule enabled ensures that new code adheres to the Constitution's absolute import philosophy without requiring manual review of every import statement.

Validating Import Compliance

To verify that the codebase respects the Constitution's import rules, run the internal codebase-mapper script located at .aios-core/infrastructure/scripts/codebase-mapper.js. This tool scans all files and reports the dominant import style:

node .aios-core/infrastructure/scripts/codebase-mapper.js

When configured correctly, the output indicates: "Import style: absolute via @/ alias" (as implemented in lines 681-686 of the script). This verification step confirms that the @/ alias is properly resolved and utilized throughout the repository, satisfying the requirements for absolute imports with the Constitution's import rules in aios-core.

Practical Import Examples

The following patterns demonstrate correct and incorrect implementations according to the AIOS Constitution.

Correct absolute import (recommended):

import { useStore } from '@/stores/feature/store';

This pattern appears in the core infrastructure, such as in .aios-core/infrastructure/scripts/pattern-extractor.js at line 754, where @/lib/utils is used to access utility functions.

Incorrect relative import (to be avoided):

import { useStore } from '../../../stores/feature/store';

Refactoring an existing file:

When modernizing legacy code, convert deep relative paths to the @/ alias:

// Before
import { foo } from '../../utils/foo';

// After
import { foo } from '@/utils/foo';

Adding a new module:

When creating new features, always reference external modules using the absolute alias:

// src/new-feature/index.ts
export * from '@/services/new-service';

Summary

Setting up absolute imports with the Constitution's import rules in aios-core requires coordinated configuration across TypeScript, Jest, and ESLint:

• Configure the @/ alias in tsconfig.json (lines 21-25) to map to ./.aios-core/core
• Update Jest's moduleNameMapper in the service template (lines 75-78) to resolve the alias during testing
• Enable the ESLint Constitution gate to warn against deep relative imports
• Validate compliance using the codebase-mapper.js script (lines 681-686), which confirms the "absolute via @/ alias" status
• Follow the style guide in .aios-core/constitution.md (lines 106-114) when writing new imports

Frequently Asked Questions

What is the AIOS Constitution's stance on relative imports?

The AIOS Constitution treats absolute imports as a SHOULD rule, meaning they are strongly recommended and enforced by tooling but allow rare exceptions for intra-feature imports within the same logical boundary. Deep relative paths like ../../../ are explicitly discouraged because they create fragile dependencies that break during refactoring.

How do I configure the @/ alias in a custom Jest setup?

If you are not using the provided service template, add the following moduleNameMapper configuration to your jest.config.js or jest.config.ts file:

moduleNameMapper: {
  '^@/(.*)$': '<rootDir>/$1'
}

This regex captures any import starting with @/ and resolves it relative to the project root, matching the TypeScript path mapping defined in tsconfig.json.

Can I disable the ESLint Constitution gate for specific files?

While the Constitution gate is non-blocking by design, you can suppress the absolute import rule for specific lines using standard ESLint disable comments. However, the AIOS team recommends following the guideline consistently across the codebase to maintain the decoupling benefits described in .aios-core/constitution.md.

How do I verify that my imports comply with the Constitution?

Run the internal validation script located at .aios-core/infrastructure/scripts/codebase-mapper.js. This tool scans the entire repository and reports the dominant import style. When configured correctly, the output will indicate "Import style: absolute via @/ alias", confirming that your absolute imports with the Constitution's import rules in aios-core are properly implemented.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}