Core Project Management

/**
 * Base project class - foundation for all projen projects
 * Extends the AWS CDK Construct class for composability
 */
class Project extends Construct {
  constructor(options: ProjectOptions);
  
  /** Project name */
  readonly name: string;
  /** Absolute output directory path */
  readonly outdir: string;
  /** Parent project for subprojects */
  readonly parent?: Project;
  /** Task management system */
  readonly tasks: Tasks;
  /** Dependency management system */
  readonly deps: Dependencies;
  /** Logging utilities */
  readonly logger: Logger;
  /** .gitignore file management */
  readonly gitignore: IgnoreFile;
  /** .gitattributes file management */
  readonly gitattributes: GitAttributesFile;
  /** Build process coordination */
  readonly projectBuild: ProjectBuild;
  
  /** Add a new task to the project */
  addTask(name: string, props?: TaskOptions): Task;
  /** Remove a task from the project */
  removeTask(name: string): Task | undefined;
  /** Synthesize all project files to disk */
  synth(): void;
  /** Find a file by relative path */
  tryFindFile(filePath: string): FileBase | undefined;
  /** Find a JSON file by relative path */
  tryFindJsonFile(filePath: string): JsonFile | undefined;
  /** Find an object file by relative path */
  tryFindObjectFile(filePath: string): ObjectFile | undefined;
  /** Remove a file from the project */
  tryRemoveFile(filePath: string): FileBase | undefined;
  /** Add a pattern to .gitignore */
  addGitIgnore(pattern: string): void;
  /** Add a tip message to be displayed after synthesis */
  addTip(message: string): void;
  /** Add glob patterns to exclude from cleanup */
  addExcludeFromCleanup(...globs: string[]): void;
  /** Add pattern to package ignore list */
  addPackageIgnore(pattern: string): void;
  /** Run a task command in the project directory */
  runTaskCommand(task: Task): void;
  /** Annotate a file pattern as generated */
  annotateGenerated(glob: string): void;
  
  /** Get the root project */
  readonly root: Project;
  /** Get all components in the project */
  readonly components: Component[];
  /** Get all subprojects */
  readonly subprojects: Project[];
  /** Get all files in the project */
  readonly files: FileBase[];
  /** Check if project has been ejected */
  readonly ejected: boolean;
  /** Default task (usually runs when `projen` is called without arguments) */
  readonly defaultTask?: Task;
  /** Build task */
  readonly buildTask: Task;
  /** Compile task */
  readonly compileTask: Task;
  /** Test task */
  readonly testTask: Task;
  /** Pre-compile task */
  readonly preCompileTask: Task;
  /** Post-compile task */
  readonly postCompileTask: Task;
  /** Package task */
  readonly packageTask: Task;
  /** Shell command to run projen CLI */
  readonly projenCommand: string;
  /** Whether generated files should be committed */
  readonly commitGenerated: boolean;
  /** Project initialization metadata (for programmatic creation) */
  readonly initProject?: InitProject;
  
  /** Type guard to check if object is a Project */
  static isProject(x: any): x is Project;
  /** Get the project instance from any construct */
  static of(construct: IConstruct): Project;
}

interface ProjectOptions {
  /** Project name - used for package.json name, directory names, etc. */
  name: string;
  /** Parent project for creating subprojects */
  parent?: Project;
  /** Output directory (default: process.cwd()) */
  outdir?: string;
  /** Logging configuration */
  logging?: LoggerOptions;
  /** Generate .projenrc.json for JSON-based configuration */
  projenrcJson?: boolean;
  /** Options for .projenrc.json */
  projenrcJsonOptions?: ProjenrcJsonOptions;
  /** Shell command to run projen CLI (default: "npx projen") */
  projenCommand?: string;
  /** Enable Renovatebot for dependency updates */
  renovatebot?: boolean;
  /** Options for renovatebot */
  renovatebotOptions?: RenovatebotOptions;
  /** Commit generated files to git (default: true) */
  commitGenerated?: boolean;
  /** Git configuration options */
  gitOptions?: GitOptions;
  /** .gitignore file configuration options */
  gitIgnoreOptions?: IgnoreFileOptions;
}

interface GitOptions {
  /** File patterns to mark as stored in Git LFS */
  lfsPatterns?: string[];
  /** The default end of line character for text files */
  endOfLine?: EndOfLine;
}

interface IgnoreFileOptions {
  /** File patterns to ignore */
  ignorePatterns?: string[];
}

interface LoggerOptions {
  /** Logging level */
  level?: LogLevel;
  /** Use prefix in log messages */
  usePrefix?: boolean;
}

enum LogLevel {
  OFF = 0,
  ERROR = 1,
  WARN = 2,
  INFO = 3,
  DEBUG = 4,
  VERBOSE = 5
}

enum EndOfLine {
  /** Maintain existing (mixed values within one file are normalised by looking at what's used after the first line) */
  AUTO = "auto",
  /** Carriage Return + Line Feed characters (\r\n), common on Windows */
  CRLF = "crlf",
  /** Line Feed only (\n), common on Linux and macOS as well as inside git repos */
  LF = "lf",
  /** Disable and do not configure the end of line character */
  NONE = "none"
}

import { Project } from "projen";

const project = new Project({
  name: "my-base-project",
  outdir: "./output",
  logging: { level: LogLevel.INFO },
  renovatebot: true,
});

// Add custom task
const buildTask = project.addTask("build", {
  description: "Build the project",
  exec: "echo 'Building project'",
});

// Synthesize files
project.synth();

/**
 * Base class for all project components
 * Provides synthesis lifecycle hooks
 */
class Component extends Construct {
  constructor(scope: IConstruct, id?: string);
  
  /** Reference to the parent project */
  readonly project: Project;
  
  /** Pre-synthesis hook - called before synthesis */
  preSynthesize(): void;
  /** Main synthesis hook - generate files and configuration */
  synthesize(): void;
  /** Post-synthesis hook - called after synthesis */
  postSynthesize(): void;
  
  /** Type guard to check if object is a Component */
  static isComponent(x: any): x is Component;
}

import { Component, Project } from "projen";

class CustomComponent extends Component {
  constructor(project: Project) {
    super(project, "custom-component");
  }
  
  synthesize() {
    // Add custom synthesis logic
    new JsonFile(this.project, "custom-config.json", {
      obj: { custom: true },
    });
  }
}

const project = new Project({ name: "test" });
new CustomComponent(project);
project.synth();

/**
 * Utility class for programmatic project creation
 * Provides factory methods for creating projects
 */
class Projects {
  /** Create a project programmatically with specified options */
  static createProject(options: CreateProjectOptions): void;
}

interface CreateProjectOptions {
  /** Directory to create the project in */
  dir: string;
  /** Project type identifier */
  projectType: string;
  /** Project configuration options */
  projectOptions: any;
  /** Skip synthesis after creation */
  skipSynth?: boolean;
}

import { Projects } from "projen";

// Create a TypeScript project programmatically
Projects.createProject({
  dir: "./my-new-project",
  projectType: "typescript",
  projectOptions: {
    name: "my-typescript-project",
    defaultReleaseBranch: "main",
  },
});

/**
 * Manages the project build process and component coordination
 */
class ProjectBuild extends Component {
  constructor(project: Project);
  
  /** Pre-build phase tasks */
  readonly preBuildTask: Task;
  /** Main build phase tasks */
  readonly buildTask: Task;
  /** Post-build phase tasks */
  readonly postBuildTask: Task;
}

/**
 * Structured logging with different levels and formatting
 */
class Logger {
  constructor(options?: LoggerOptions);
  
  /** Log verbose message (level 5) */
  verbose(message: string): void;
  /** Log debug message (level 4) */
  debug(message: string): void;
  /** Log info message (level 3) */
  info(message: string): void;
  /** Log warning message (level 2) */
  warn(message: string): void;
  /** Log error message (level 1) */
  error(message: string): void;
}

import { Logger, LogLevel } from "projen";

const logger = new Logger({
  level: LogLevel.DEBUG,
  usePrefix: true,
});

logger.info("Starting project synthesis");
logger.debug("Component configuration loaded");
logger.warn("Deprecated option used");