Workspace Utilities

/**
 * Reads the Angular workspace configuration from angular.json
 * @param tree - The virtual file system tree
 * @param path - Optional path to workspace file (defaults to '/angular.json')
 * @returns Promise resolving to workspace definition
 */
function readWorkspace(tree: Tree, path?: string): Promise<WorkspaceDefinition>;

/**
 * Legacy function name, alias for readWorkspace
 * @deprecated Use readWorkspace instead
 */
function getWorkspace(tree: Tree, path?: string): Promise<WorkspaceDefinition>;

import { readWorkspace } from '@schematics/angular/utility';

export function mySchematic(): Rule {
  return async (tree: Tree) => {
    const workspace = await readWorkspace(tree);
    
    // Access projects
    const defaultProject = workspace.projects.get('my-app');
    console.log('Project root:', defaultProject?.root);
    
    return tree;
  };
}

/**
 * Updates workspace configuration using an updater function
 * @param updater - Function that receives workspace and can modify it
 * @returns Rule that applies the workspace changes
 */
function updateWorkspace(
  updater: (workspace: WorkspaceDefinition) => void | PromiseLike<void>
): Rule;

/**
 * Writes workspace definition to angular.json file
 * @param workspace - Workspace definition to write
 * @param tree - Virtual file system tree
 * @param path - Optional path to workspace file (defaults to '/angular.json')
 */
function writeWorkspace(
  workspace: WorkspaceDefinition, 
  tree: Tree, 
  path?: string
): void;

import { updateWorkspace } from '@schematics/angular/utility';

export function addBuildTarget(): Rule {
  return updateWorkspace((workspace) => {
    const project = workspace.projects.get('my-app');
    if (project) {
      project.targets.set('custom-build', {
        builder: '@angular-devkit/build-angular:browser',
        options: {
          outputPath: 'dist/custom'
        }
      });
    }
  });
}

/**
 * Gets a project from workspace by name, throws if not found
 * @param workspace - The workspace definition
 * @param projectName - Name of the project to retrieve
 * @returns Project definition
 * @throws Error if project is not found
 */
function getProject(
  workspace: WorkspaceDefinition, 
  projectName: string
): ProjectDefinition;

/**
 * Checks if a project is a workspace project (not external)
 * @param project - Project definition to check
 * @returns True if project is a workspace project
 */
function isWorkspaceProject(project: ProjectDefinition): boolean;

/**
 * Checks if workspace follows the workspace schema format
 * @param workspace - Workspace to validate
 * @returns True if workspace is valid
 */
function isWorkspaceSchema(workspace: WorkspaceDefinition): boolean;

/**
 * Builds the default path for generating files within a project
 * @param project - Project definition
 * @returns Default path string (typically sourceRoot + '/app')
 */
function buildDefaultPath(project: ProjectDefinition): string;

/**
 * Builds a relative path from project root to workspace root
 * @param projectRoot - Project root directory
 * @returns Relative path string
 */
function relativePathToWorkspaceRoot(projectRoot: string): string;

/**
 * Builds a relative path between two absolute paths
 * @param from - Source path
 * @param to - Target path  
 * @returns Relative path string
 */
function buildRelativePath(from: string, to: string): string;

import { buildDefaultPath, getProject } from '@schematics/angular/utility';

export function generateComponent(): Rule {
  return async (tree: Tree) => {
    const workspace = await readWorkspace(tree);
    const project = getProject(workspace, 'my-app');
    
    // Get default path: /src/app
    const defaultPath = buildDefaultPath(project);
    
    // Create component in default location
    tree.create(`${defaultPath}/my-component.ts`, componentContent);
    
    return tree;
  };
}

/**
 * A WorkspaceHost implementation backed by a Schematics Tree
 * Provides file system operations for workspace manipulation
 */
class TreeWorkspaceHost implements workspaces.WorkspaceHost {
  constructor(tree: Tree);
  
  /**
   * Reads file content as string
   * @param path - File path to read
   * @returns Promise resolving to file content
   */
  readFile(path: string): Promise<string>;
  
  /**
   * Writes file content
   * @param path - File path to write
   * @param data - Content to write
   */
  writeFile(path: string, data: string): Promise<void>;
  
  /**
   * Checks if path is a directory
   * @param path - Path to check
   * @returns Promise resolving to boolean
   */
  isDirectory(path: string): Promise<boolean>;
  
  /**
   * Checks if path is a file
   * @param path - Path to check
   * @returns Promise resolving to boolean
   */
  isFile(path: string): Promise<boolean>;
}

interface WorkspaceDefinition {
  /** Map of project names to project definitions */
  projects: Map<string, ProjectDefinition>;
  /** Additional workspace-level configuration */
  extensions: Record<string, JsonValue>;
  /** Default project name */
  defaultProject?: string;
  /** Workspace version */
  version: number;
  /** New project root directory */
  newProjectRoot?: string;
  /** CLI configuration */
  cli?: Record<string, JsonValue>;
  /** Schematics configuration */
  schematics?: Record<string, JsonValue>;
  /** Architect configuration */
  architect?: Record<string, JsonValue>;
}

interface ProjectDefinition {
  /** Project root directory relative to workspace */
  root: string;
  /** Source root directory relative to workspace */
  sourceRoot?: string;
  /** Project type (application or library) */
  projectType?: ProjectType;
  /** Map of target names to target definitions */
  targets: Map<string, TargetDefinition>;
  /** Additional project-level configuration */
  extensions: Record<string, JsonValue>;
  /** Project prefix for generated selectors */
  prefix?: string;
  /** Schematics configuration for this project */
  schematics?: Record<string, JsonValue>;
  /** Architect configuration for this project */
  architect?: Record<string, JsonValue>;
}

interface TargetDefinition {
  /** Builder to use for this target */
  builder: string;
  /** Default configuration to use */
  defaultConfiguration?: string;
  /** Named configurations */
  configurations?: Record<string, Record<string, JsonValue>>;
  /** Default options */
  options?: Record<string, JsonValue>;
}

enum ProjectType {
  Application = 'application',
  Library = 'library'
}

enum Builders {
  Application = '@angular-devkit/build-angular:application',
  Browser = '@angular-devkit/build-angular:browser',
  DevServer = '@angular-devkit/build-angular:dev-server',
  Karma = '@angular-devkit/build-angular:karma',
  Protractor = '@angular-devkit/build-angular:protractor',
  Extract = '@angular-devkit/build-angular:extract-i18n',
  NgPackagr = 'ng-packagr:build',
  Lint = '@angular-eslint/builder:lint'
}