azcodr 2.7.0 → 2.7.1

package/src/agent-guard-tdd.ts

@@ -1,18 +1,36 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+/**
+ * Persistent state tracking test-first TDD progress across an agent session.
+ */
 export interface SessionTddState {
+  /** Whether a failing test execution (RED phase) has been recorded in the session. */
   lastFailingTestRecorded: boolean;
+  /** Unix timestamp in milliseconds when the last test execution occurred. */
   lastTestRunTime?: number;
+  /** File path of the most recently executed test file. */
   lastTestPath?: string;
 }
 
+/**
+ * Result of evaluating a file edit against RED-before-GREEN TDD rules.
+ */
 export interface TddCheckResult {
+  /** Whether the file edit is blocked due to missing failing test. */
   blocked: boolean;
+  /** Explanatory reason if the operation is blocked. */
   reason?: string;
+  /** Whether the target file was identified as production source code. */
   isProductionFile: boolean;
 }
 
+/**
+ * Identifies whether a given path is a unit or integration test file.
+ *
+ * @param filePath - File path to inspect.
+ * @returns True if path matches test directory or file extension patterns.
+ */
 export function isTestFile(filePath: string): boolean {
   const norm = filePath.replace(/\\/g, '/').toLowerCase();
   if (/(^|\/)(tests?|__tests__)(\/|$)/i.test(norm)) {
@@ -21,12 +39,24 @@ export function isTestFile(filePath: string): boolean {
   return /\.(test|spec)\.[a-z0-9]+$/i.test(norm);
 }
 
+/**
+ * Identifies whether a given path is a non-code file (markdown, json, yaml, images).
+ *
+ * @param filePath - File path to inspect.
+ * @returns True if file extension indicates non-code asset or configuration.
+ */
 export function isNonCodeFile(filePath: string): boolean {
   const ext = path.extname(filePath).toLowerCase();
   const nonCodeExts = new Set(['.md', '.json', '.yml', '.yaml', '.txt', '.toml', '.lock', '.svg', '.png']);
   return nonCodeExts.has(ext);
 }
 
+/**
+ * Identifies whether a given file path corresponds to production code under src/, lib/, or app/.
+ *
+ * @param filePath - File path to inspect.
+ * @returns True if path is production source code subject to RED-before-GREEN discipline.
+ */
 export function isProductionFile(filePath: string): boolean {
   if (isNonCodeFile(filePath)) return false;
   if (isTestFile(filePath)) return false;
@@ -34,6 +64,12 @@ export function isProductionFile(filePath: string): boolean {
   return norm.includes('src/') || norm.includes('lib/') || norm.includes('app/');
 }
 
+/**
+ * Loads session TDD tracking state from disk, defaulting to unrecorded state if missing.
+ *
+ * @param stateFile - Path to the persistent session state JSON file.
+ * @returns Parsed SessionTddState object.
+ */
 export function readTddState(stateFile: string): SessionTddState {
   if (!fs.existsSync(stateFile)) {
     return { lastFailingTestRecorded: false };
@@ -46,6 +82,12 @@ export function readTddState(stateFile: string): SessionTddState {
   }
 }
 
+/**
+ * Persists session TDD state to disk with fail-safe error handling to avoid disrupting execution.
+ *
+ * @param stateFile - Path to the persistent session state JSON file.
+ * @param state - SessionTddState object to record.
+ */
 export function writeTddState(stateFile: string, state: SessionTddState): void {
   try {
     const dir = path.dirname(stateFile);

package/src/agent-guard.ts

@@ -10,20 +10,37 @@ import {
 } from './agent-guard-tdd.js';
 import type { SessionTddState } from './agent-guard-tdd.js';
 
+/**
+ * Verdict returned by agent-runtime safety and architecture inspection guards.
+ */
 export interface GuardDecision {
+  /** Whether the requested tool operation is permitted. */
   allowed: boolean;
+  /** Explanatory failure reason when the action is blocked. */
   reason?: string;
+  /** Subsystem that produced the decision ('command', 'file', or 'tdd'). */
   source?: 'command' | 'file' | 'tdd';
 }
 
+/**
+ * Normalized representation of an agent tool invocation payload.
+ */
 export interface ToolEnvelope {
+  /** Name of the tool invoked by the agent. */
   tool_name?: string;
+  /** Parameter payload passed to the tool invocation. */
   tool_input?: Record<string, unknown>;
 }
 
+/**
+ * Configuration options governing agent guard enforcement behavior.
+ */
 export interface GuardOptions {
+  /** Target workspace root directory (defaults to process.cwd()). */
   workspaceRoot?: string;
+  /** When true, strictly mandates RED failing test before modifying production code. */
   enforceTestFirst?: boolean;
+  /** Maximum non-overflow file line threshold before Refactor-Before-Add triggers. */
   maxFileLines?: number;
 }
 

package/src/boundaries.ts

@@ -1,25 +1,47 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+/**
+ * Defines an architectural layer boundary rule disallowing imports from foreign layers.
+ */
 export interface BoundaryRule {
+  /** Name of the architectural layer (e.g., 'domain', 'core'). */
   fromLayer: string;
+  /** Array of layer names that fromLayer is forbidden from importing. */
   disallowImportsFrom: readonly string[];
 }
 
+/**
+ * Represents an architectural boundary violation where a module imported a prohibited layer.
+ */
 export interface BoundaryViolation {
+  /** Path of the file containing the illegal import. */
   file: string;
+  /** Path of the imported file that violates the rule. */
   importedFile: string;
+  /** Origin layer of the importing file. */
   fromLayer: string;
+  /** Target layer that was forbidden to import. */
   toLayer: string;
 }
 
+/**
+ * Report summarizing module count, detected circular cycles, and boundary violations.
+ */
 export interface BoundaryReport {
+  /** Total number of source modules scanned. */
   moduleCount: number;
+  /** List of detected circular dependency cycles. */
   cycles: string[][];
+  /** List of detected boundary violations. */
   violations: BoundaryViolation[];
+  /** Whether the architecture is completely compliant (no cycles and no violations). */
   ok: boolean;
 }
 
+/**
+ * Canonical architectural boundary rules enforcing Hexagonal / Clean Architecture layer constraints.
+ */
 export const DEFAULT_BOUNDARY_RULES: readonly BoundaryRule[] = [
   {
     fromLayer: 'domain',
@@ -41,6 +63,13 @@ function isEligibleSource(name: string): boolean {
   return !name.includes('.test.') && !name.includes('.spec.');
 }
 
+/**
+ * Recursively discovers all eligible source files (.ts and .js) within a directory,
+ * ignoring skipped directories (e.g. node_modules, lib) and test files.
+ *
+ * @param dir - Root directory to search.
+ * @returns Sorted array of absolute file paths.
+ */
 export function findSourceFiles(dir: string): string[] {
   if (!fs.existsSync(dir)) return [];
   const results: string[] = [];
@@ -71,6 +100,12 @@ function resolveImportTarget(sourceFile: string, specifier: string): string | nu
   return null;
 }
 
+/**
+ * Scans a source file and extracts all local relative import and export paths.
+ *
+ * @param filePath - Absolute or relative path to the source file.
+ * @returns Sorted array of resolved local file paths imported or re-exported.
+ */
 export function extractLocalImports(filePath: string): string[] {
   if (!fs.existsSync(filePath)) return [];
   const content = fs.readFileSync(filePath, 'utf-8');
@@ -90,6 +125,12 @@ export function extractLocalImports(filePath: string): string[] {
   return imports.sort();
 }
 
+/**
+ * Constructs a dependency graph mapping each source file to its imported local files.
+ *
+ * @param files - Array of source file paths.
+ * @returns Map where keys are source file paths and values are arrays of imported local file paths.
+ */
 export function buildDependencyGraph(files: readonly string[]): Map<string, string[]> {
   const graph = new Map<string, string[]>();
   for (const file of files) {
@@ -98,6 +139,12 @@ export function buildDependencyGraph(files: readonly string[]): Map<string, stri
   return graph;
 }
 
+/**
+ * Analyzes a dependency graph using depth-first search to detect circular import cycles.
+ *
+ * @param graph - Map of file paths to their imported dependency file paths.
+ * @returns Array of cycle paths, where each cycle path is an array of file paths.
+ */
 export function detectDependencyCycles(graph: Map<string, string[]>): string[][] {
   const cycles: string[][] = [];
   const visited = new Set<string>();
@@ -135,6 +182,13 @@ function hasLayerSegment(pathStr: string, segment: string): boolean {
   return new RegExp(`(^|[/\\\\])${segment}([/\\\\]|$)`, 'i').test(pathStr);
 }
 
+/**
+ * Evaluates a dependency graph against architectural boundary rules to detect prohibited cross-layer imports.
+ *
+ * @param graph - Map of file paths to their imported dependency file paths.
+ * @param rules - Architectural boundary rules to enforce (defaults to DEFAULT_BOUNDARY_RULES).
+ * @returns Array of detected boundary violations.
+ */
 export function detectBoundaryViolations(
   graph: Map<string, string[]>,
   rules: readonly BoundaryRule[] = DEFAULT_BOUNDARY_RULES

package/src/errors.ts

@@ -7,11 +7,17 @@
  * tests/error-codes.test.js.
  */
 export const ERROR_CODES = {
+  /** Target directory matches template repository root itself. */
   E_TARGET_IS_TEMPLATE: 'Cannot scaffold into the azcodr template directory itself',
+  /** Target directory exists and already contains non-empty files without --force. */
   E_TARGET_NOT_EMPTY: 'Target directory is not empty',
+  /** Target path matches protected system, home, or root directory. */
   E_TARGET_IS_PROTECTED: 'Refusing to scaffold into a protected system directory',
+  /** runGit invoked with empty or missing argument array. */
   E_GIT_ARGS_INVALID: 'runGit requires a non-empty argv array',
+  /** Attempted git subcommand not in the explicit allowlist. */
   E_GIT_BLOCKED: 'Blocked git subcommand',
+  /** Relative path navigation escapes allowed root directory. */
   E_PATH_ESCAPE: 'Path escapes allowed root'
 } as const;
 
@@ -24,7 +30,9 @@ export type ScaffoldErrorCode = keyof typeof ERROR_CODES;
  * Structural interface contract for errors thrown by the scaffolder.
  */
 export interface ScaffoldErrorShape extends Error {
+  /** Error class discriminator name. */
   name: 'ScaffoldError';
+  /** Machine-readable error code. */
   code: ScaffoldErrorCode;
 }
 
@@ -32,7 +40,9 @@ export interface ScaffoldErrorShape extends Error {
  * Custom error class thrown by scaffolding operations, carrying a machine-readable code.
  */
 export class ScaffoldError extends Error implements ScaffoldErrorShape {
+  /** Error class name identifier. */
   override readonly name: 'ScaffoldError' = 'ScaffoldError';
+  /** Machine-readable error code identifying failure cause. */
   readonly code: ScaffoldErrorCode;
 
   /**

package/src/guards.ts

@@ -19,9 +19,13 @@ export function getTemplateDir(): string {
  * Options for configuring protected target verification.
  */
 export interface ProtectedTargetOptions {
+  /** Optional custom template directory path. */
   templateDir?: string;
+  /** Force overwrite flag. */
   force?: boolean;
+  /** Dry-run execution simulation flag. */
   dryRun?: boolean;
+  /** Allow targeting protected directories (internal testing only). */
   allowProtected?: boolean;
 }
 

package/src/links.ts

@@ -5,9 +5,13 @@ import path from 'node:path';
  * Configuration options for symlink and pointer creation.
  */
 export interface EnsureSymlinkOptions {
+  /** Target directory containing the files and proposed link. */
   targetDir: string;
+  /** Name of the symbolic link or alias pointer file to create. */
   linkName: string;
+  /** Name of the target file that the symlink or pointer points to. */
   targetFileName: string;
+  /** When true, simulate link creation without disk mutations. */
   dryRun?: boolean;
 }
 

package/src/repo.ts

@@ -9,7 +9,9 @@ const INITIAL_COMMIT_MESSAGE = 'chore: initial scaffold from azcodr template';
  * Options controlling git repository initialization.
  */
 export interface InitGitOptions {
+  /** If true, skip git repository initialization entirely. */
   noGit?: boolean;
+  /** If true, simulate git repository initialization without invoking git. */
   dryRun?: boolean;
 }
 

package/src/scaffold.ts

@@ -34,11 +34,17 @@ export const TEMPLATE_ITEMS: readonly string[] = [
  * Configuration options for the primary scaffold orchestration function.
  */
 export interface ScaffoldOptions {
+  /** Target directory path where project will be scaffolded (defaults to process.cwd()). */
   targetDir?: string;
+  /** Force overwrite if target directory exists and is non-empty. */
   force?: boolean;
+  /** Skip git repository initialization. */
   noGit?: boolean;
+  /** Optional custom template directory path. */
   templateDir?: string;
+  /** Simulate scaffolding without writing files to disk. */
   dryRun?: boolean;
+  /** Suppress non-error console output. */
   silent?: boolean;
 }
 
@@ -46,10 +52,15 @@ export interface ScaffoldOptions {
  * Result object returned upon completion of a scaffold operation.
  */
 export interface ScaffoldResult {
+  /** Whether the scaffolding operation completed successfully. */
   success: boolean;
+  /** Absolute filesystem path of the scaffolded target directory. */
   targetDir: string;
+  /** Whether a git repository was initialized and committed. */
   gitInitialized: boolean;
+  /** Whether execution was a dry-run simulation without disk mutations. */
   dryRun: boolean;
+  /** List of recorded scaffolding action descriptions taken. */
   actions: string[];
 }
 
@@ -57,9 +68,13 @@ export interface ScaffoldResult {
  * Options controlling pre-scaffold target directory validation.
  */
 export interface ValidateTargetOptions {
+  /** Custom template root directory path. */
   templateDir?: string;
+  /** Allow non-empty directory when force is true. */
   force?: boolean;
+  /** Simulate validation checks without erroring on non-empty targets. */
   dryRun?: boolean;
+  /** Allow targeting protected directories (internal testing only). */
   allowProtected?: boolean;
 }
 
@@ -67,10 +82,10 @@ export interface ValidateTargetOptions {
  * Options controlling template file copying and file generation.
  */
 export interface CopyTemplateOptions {
+  /** Simulate copying without disk mutations. */
   dryRun?: boolean;
 }
 
-
 function rejectTemplateSelf(resolvedTarget: string, resolvedTemplate: string): void {
   if (resolvedTarget !== resolvedTemplate) return;
   throw new ScaffoldError(
@@ -253,11 +268,8 @@ export function copyTemplate(
  */
 export function scaffold(options: ScaffoldOptions = {}): ScaffoldResult {
   const {
-    targetDir = process.cwd(),
-    force = false,
-    noGit = false,
-    templateDir = getTemplateDir(),
-    dryRun = false
+    targetDir = process.cwd(), force = false,
+    noGit = false, templateDir = getTemplateDir(), dryRun = false
   } = options;
   const resolvedTarget = path.resolve(targetDir);
   validateTarget(resolvedTarget, { templateDir, force, dryRun });
@@ -272,9 +284,11 @@ export {
   makeScriptsExecutable, isInsideGitWorkTree, initGit, runGit,
   assertInside, ScaffoldError, ERROR_CODES, isProtectedTarget
 };
-
 export type { EnsureSymlinkOptions, InitGitOptions, ScaffoldErrorCode, ScaffoldErrorShape };
 
+/**
+ * Unified azcodr scaffolding functions, guards, utilities, and constants module.
+ */
 export default {
   scaffold, validateTarget, copyTemplate, ensureSymlink,
   ensureSymlinkOrPointer, isSameCaseInsensitiveFile, makeScriptsExecutable,

package/src/validate.ts

@@ -1,20 +1,37 @@
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+/**
+ * Tally and results returned by the architecture governance validator.
+ */
 export interface ValidationResult {
+  /** Total count of fatal governance errors encountered. */
   errors: number;
+  /** Total count of non-fatal governance warnings encountered. */
   warnings: number;
+  /** Number of progressive disclosure domain rule files verified. */
   validatedRules: number;
+  /** Number of agent skills verified under .agents/skills/. */
   validatedSkills: number;
+  /** Total count of internal markdown links verified. */
   totalLinks: number;
+  /** List of broken link targets detected across workspace markdown files. */
   brokenLinks: string[];
 }
 
+/**
+ * Pluggable reporter interface receiving live validation events.
+ */
 export interface ValidationReporter {
+  /** Called when a check passes. */
   pass: (msg: string) => void;
+  /** Called when a non-fatal warning is raised. */
   warn: (msg: string) => void;
+  /** Called when a validation check fails. */
   fail: (msg: string) => void;
+  /** Called for informative messages and section spacing. */
   log: (msg: string) => void;
+  /** Called when a new validation phase begins. */
   heading: (msg: string) => void;
 }