Package Exports

@harness-engineering/core
@harness-engineering/core/architecture/matchers

Readme

@harness-engineering/core

Core library for Harness Engineering toolkit - provides runtime APIs for context engineering, architectural constraints, agent feedback, and entropy management.

Installation

pnpm add @harness-engineering/core

Modules

Modules Overview

Module	Description
validation	Cross-cutting validation for file structure, configuration, and commit messages
context	AGENTS.md knowledge maps, documentation coverage analysis, token budgets, and context filtering
constraints	Architectural layer enforcement, circular dependency detection, and boundary validation
entropy	Documentation drift, dead code detection, pattern violations, and auto-fix
architecture	Metric collection via multiple collectors (circular deps, layer violations, complexity, coupling, forbidden imports, module size, dependency depth)
review	Code review pipeline with mechanical checks, fan-out agents (compliance, bugs, security, architecture), and deduplication
feedback	Agent feedback loops with self-review, peer review, telemetry, logging, and action tracking
performance	Benchmarking, baseline management, regression detection, and critical path analysis
security	Security scanning with secret detection, injection detection, XSS, crypto, path traversal, and stack-specific rules (Node.js, Express, React, Go)
ci	CI/CD check orchestration for running automated checks in continuous integration pipelines
code-nav	Code navigation: file parsing, symbol extraction/outlines, symbol search, and code range unfolding by language
state	State persistence including learnings, failures, handoffs, gates, streams, sessions, and event logging
roadmap	Roadmap parsing, serialization, and synchronization with codebase and issue tracking
pipeline	Skill pipeline orchestration for sequential and multi-turn skill execution
workflow	Workflow execution engine for structured multi-step workflows
interaction	Types and schemas for agent-to-human interactions (questions, confirmations, transitions)
blueprint	HTML documentation generation from module data using EJS templates
pricing	LiteLLM-based model pricing lookup, disk cache with 24h TTL, bundled fallback, and microdollar cost calculation
shared	Error types, Result pattern for error handling, file system utilities, and language parsers

Validation Module

Cross-cutting validation utilities used by all other modules.

File Structure Validation

Verify project follows file structure conventions:

import { validateFileStructure, type Convention } from '@harness-engineering/core';

const conventions: Convention[] = [
  {
    pattern: 'README.md',
    required: true,
    description: 'Project README',
    examples: ['README.md'],
  },
  {
    pattern: 'AGENTS.md',
    required: true,
    description: 'Knowledge map',
    examples: ['AGENTS.md'],
  },
];

const result = await validateFileStructure('./my-project', conventions);

if (result.ok) {
  console.log('Valid:', result.value.valid);
  console.log('Conformance:', result.value.conformance + '%');
  console.log('Missing:', result.value.missing);
} else {
  console.error('Error:', result.error.message);
}

Config Validation

Type-safe configuration validation with Zod:

import { validateConfig } from '@harness-engineering/core';
import { z } from 'zod';

const ConfigSchema = z.object({
  version: z.number(),
  layers: z.array(
    z.object({
      name: z.string(),
      allowedDependencies: z.array(z.string()),
    })
  ),
});

const result = validateConfig(userConfig, ConfigSchema);

if (result.ok) {
  // TypeScript knows result.value matches ConfigSchema
  console.log('Config version:', result.value.version);
} else {
  console.error('Validation failed:', result.error.message);
  console.error('Suggestions:', result.error.suggestions);
}

Commit Message Validation

Validate commit messages follow conventional format:

import { validateCommitMessage } from '@harness-engineering/core';

const result = validateCommitMessage('feat(core): add validation module', 'conventional');

if (result.ok) {
  if (result.value.valid) {
    console.log('Type:', result.value.type); // 'feat'
    console.log('Scope:', result.value.scope); // 'core'
    console.log('Breaking:', result.value.breaking); // false
  } else {
    console.log('Issues:', result.value.issues);
  }
}

Context Engineering Module

Tools for validating and generating AGENTS.md knowledge maps.

AGENTS.md Validation

Validate the structure and links in an AGENTS.md file:

import { validateAgentsMap } from '@harness-engineering/core';

const result = await validateAgentsMap('./AGENTS.md');

if (result.ok) {
  console.log('Valid:', result.value.valid);
  console.log('Sections:', result.value.sections.length);
  console.log('Broken links:', result.value.brokenLinks.length);
  console.log('Missing sections:', result.value.missingSections);
}

Documentation Coverage

Check how well your code is documented:

import { checkDocCoverage } from '@harness-engineering/core';

const result = await checkDocCoverage('src', {
  docsDir: './docs',
  sourceDir: './src',
  excludePatterns: ['**/*.test.ts'],
});

if (result.ok) {
  console.log('Coverage:', result.value.coveragePercentage + '%');
  console.log('Gaps:', result.value.gaps);
}

Knowledge Map Integrity

Verify all links in your AGENTS.md point to existing files:

import { validateKnowledgeMap } from '@harness-engineering/core';

const result = await validateKnowledgeMap('./');

if (result.ok) {
  console.log('Integrity:', result.value.integrity + '%');
  for (const broken of result.value.brokenLinks) {
    console.log(`Broken: ${broken.path} - ${broken.suggestion}`);
  }
}

AGENTS.md Generation

Auto-generate an AGENTS.md from your project structure:

import { generateAgentsMap } from '@harness-engineering/core';

const result = await generateAgentsMap({
  rootDir: './',
  includePaths: ['**/*.md', 'src/**/*.ts'],
  excludePaths: ['node_modules/**'],
  sections: [{ name: 'API Docs', pattern: 'docs/api/**/*.md', description: 'API documentation' }],
});

if (result.ok) {
  console.log(result.value); // Generated markdown content
}

Architectural Constraints Module

Tools for enforcing layered architecture and detecting dependency issues.

Layer Validation

Define and validate architectural layers:

import { validateDependencies, defineLayer, TypeScriptParser } from '@harness-engineering/core';

const result = await validateDependencies({
  layers: [
    defineLayer('domain', ['src/domain/**'], []),
    defineLayer('services', ['src/services/**'], ['domain']),
    defineLayer('api', ['src/api/**'], ['services', 'domain']),
  ],
  rootDir: './src',
  parser: new TypeScriptParser(),
});

if (result.ok && !result.value.valid) {
  for (const violation of result.value.violations) {
    console.log(`${violation.file}:${violation.line} - ${violation.reason}`);
    console.log(`  ${violation.fromLayer} cannot import from ${violation.toLayer}`);
  }
}

Circular Dependency Detection

Find cycles in your dependency graph:

import { detectCircularDepsInFiles, TypeScriptParser } from '@harness-engineering/core';

const result = await detectCircularDepsInFiles(
  ['src/a.ts', 'src/b.ts', 'src/c.ts'],
  new TypeScriptParser()
);

if (result.ok && result.value.hasCycles) {
  for (const cycle of result.value.cycles) {
    console.log('Cycle found:', cycle.cycle.join(' -> '));
  }
}

Boundary Validation

Validate data at module boundaries:

import { z } from 'zod';
import { createBoundaryValidator } from '@harness-engineering/core';

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1),
});

const validator = createBoundaryValidator(UserSchema, 'UserService.createUser');

const result = validator.parse(requestBody);
if (result.ok) {
  // result.value is typed as { email: string; name: string }
  createUser(result.value);
} else {
  console.error(result.error.suggestions);
}

Entropy Management Module

Detect and fix codebase entropy: documentation drift, dead code, and pattern violations.

Quick Analysis

import { EntropyAnalyzer } from '@harness-engineering/core';

const analyzer = new EntropyAnalyzer({
  rootDir: './src',
  analyze: {
    drift: true,
    deadCode: true,
    patterns: {
      patterns: [
        {
          name: 'max-exports',
          description: 'Limit exports per file',
          severity: 'warning',
          files: ['**/*.ts'],
          rule: { type: 'max-exports', count: 10 },
        },
      ],
    },
  },
  include: ['**/*.ts'],
  docPaths: ['docs/**/*.md'],
});

const result = await analyzer.analyze();

if (result.ok) {
  console.log(`Found ${result.value.summary.totalIssues} issues`);
  console.log(`${result.value.summary.fixableCount} can be auto-fixed`);
}

Full Analyzer Workflow

import { EntropyAnalyzer, createFixes, applyFixes } from '@harness-engineering/core';

const analyzer = new EntropyAnalyzer({
  rootDir: './src',
  analyze: { drift: true, deadCode: true },
});

// Run analysis
const report = await analyzer.analyze();
if (!report.ok) throw new Error(report.error.message);

// Get suggestions for manual fixes
const suggestions = analyzer.getSuggestions();
console.log(`${suggestions.suggestions.length} suggestions generated`);

// Auto-fix safe issues
if (report.value.deadCode) {
  const fixes = createFixes(report.value.deadCode, {
    fixTypes: ['unused-imports', 'dead-files'],
    dryRun: true, // Preview first
  });

  console.log(
    'Preview:',
    fixes.map((f) => f.description)
  );

  // Apply for real
  await applyFixes(fixes, { dryRun: false, createBackup: true });
}

Error Handling

All APIs use the Result<T, E> pattern for type-safe error handling:

import { type Result, Ok, Err } from '@harness-engineering/core';

const result: Result<string, Error> = Ok('success');

if (result.ok) {
  console.log(result.value); // TypeScript knows this is string
} else {
  console.error(result.error); // TypeScript knows this is Error
}

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Type checking
pnpm typecheck

# Build
pnpm build

# Lint
pnpm lint

License

MIT