# Project Analysis Schema
# Defines the structure for project analysis output

version: "1.0"
description: Schema for analyzing project structure before documentation generation

project_analysis:
  project:
    type: object
    required: true
    fields:
      name:
        type: string
        required: true
        source: package.json/name or directory name
      version:
        type: string
        required: false
        source: package.json/version
      description:
        type: string
        required: false
        source: package.json/description or README.md first paragraph
      type:
        type: enum
        values: [node, python, rust, go, java, dotnet, ruby, php, other]
        detection:
          node: package.json
          python: requirements.txt, pyproject.toml, setup.py
          rust: Cargo.toml
          go: go.mod
          java: pom.xml, build.gradle
          dotnet: "*.csproj, *.sln"
          ruby: Gemfile
          php: composer.json
      repository:
        type: string
        source: package.json/repository or .git/config

  tech_stack:
    type: object
    required: true
    fields:
      language:
        type: string
        description: Primary programming language
      framework:
        type: string
        description: Main application framework
        detection:
          next: "next" in dependencies
          react: "react" in dependencies without "next"
          vue: "vue" in dependencies
          angular: "@angular/core" in dependencies
          express: "express" in dependencies
          fastapi: "fastapi" in requirements
          django: "django" in requirements
          flask: "flask" in requirements
          rails: "rails" in Gemfile
      database:
        type: string
        description: Database system if any
        detection:
          prisma: "@prisma/client" in dependencies
          mongoose: "mongoose" in dependencies
          typeorm: "typeorm" in dependencies
          sequelize: "sequelize" in dependencies
          sqlalchemy: "sqlalchemy" in requirements
      ui_framework:
        type: string
        description: UI component framework if any
        detection:
          tailwind: "tailwindcss" in devDependencies
          mui: "@mui/material" in dependencies
          chakra: "@chakra-ui/react" in dependencies
          shadcn: "shadcn" patterns in components
      key_dependencies:
        type: array
        items:
          name: string
          version: string
          purpose: string  # Plain English explanation
        categorization:
          core: Framework, runtime dependencies
          database: ORM, database clients
          auth: Authentication libraries
          ui: UI component libraries
          testing: Test frameworks
          build: Build tools, bundlers
          utility: Helper libraries

  structure:
    type: object
    required: true
    fields:
      source_dir:
        type: string
        description: Main source code directory
        detection:
          - src/
          - app/
          - lib/
          - source/
      directories:
        type: array
        items:
          path: string
          purpose: string  # Plain English description
          file_count: integer
          key_files: array
        common_mappings:
          src/components: "UI components"
          src/pages: "Application pages/routes"
          src/api: "API route handlers"
          src/lib: "Utility functions and shared code"
          src/hooks: "Custom React hooks"
          src/context: "React context providers"
          src/store: "State management"
          src/types: "TypeScript type definitions"
          src/styles: "Global styles and themes"
          prisma/: "Database schema and migrations"
          public/: "Static assets"
          tests/: "Test files"
          __tests__/: "Test files (Jest convention)"

  features:
    type: array
    description: Main features/capabilities of the project
    items:
      name: string
      description: string  # Plain English
      technical_notes: string  # For engineers
      files: array  # Key file paths
    detection_patterns:
      authentication:
        keywords: [auth, login, logout, session, jwt, oauth]
        files: ["**/auth/**", "**/login/**"]
      user_management:
        keywords: [user, profile, account, register, signup]
        files: ["**/user/**", "**/users/**"]
      api:
        keywords: [api, endpoint, route, handler]
        files: ["**/api/**", "**/routes/**"]
      database:
        keywords: [model, entity, schema, migration, prisma]
        files: ["**/models/**", "**/prisma/**"]
      file_upload:
        keywords: [upload, file, storage, s3, blob]
        files: ["**/upload/**", "**/storage/**"]
      search:
        keywords: [search, filter, query]
        files: ["**/search/**"]
      notifications:
        keywords: [notification, email, sms, push]
        files: ["**/notification/**", "**/email/**"]

  components:
    type: array
    description: UI components found in the project
    items:
      id: string  # component_<name>
      name: string  # PascalCase
      path: string
      description: string
      props: string  # Props summary
      dependencies: array  # Imported components
    detection:
      react: "export (default )?(function|const) [A-Z]"
      vue: "<template>.*<script>"
      angular: "@Component"

  api_endpoints:
    type: array
    description: API endpoints found in the project
    items:
      method: enum [GET, POST, PUT, PATCH, DELETE]
      path: string
      handler_file: string
      description: string
      technical_notes: string
    detection:
      next_app_router: "app/api/**/route.ts exports GET, POST, etc."
      next_pages_router: "pages/api/**/*.ts"
      express: "router.get/post/put/delete"
      fastapi: "@app.get/post/put/delete"

  data_models:
    type: array
    description: Data models/entities found
    items:
      name: string
      description: string  # Plain English
      fields: array
      relations: array
    detection:
      prisma: "model [A-Z][a-z]+ {"
      typeorm: "@Entity"
      mongoose: "new Schema"
      sqlalchemy: "class.*Base"

  glossary_terms:
    type: array
    description: Technical terms that need definitions
    items:
      term: string
      definition: string  # Plain English
    auto_detection:
      - Acronyms (all caps words)
      - Framework-specific terms
      - Domain-specific terminology
      - Technical jargon from code comments

analysis_process:
  steps:
    1_identify_type:
      description: Determine project type from config files
      files_to_check:
        - package.json
        - requirements.txt
        - pyproject.toml
        - Cargo.toml
        - go.mod
        - pom.xml

    2_scan_structure:
      description: Map directory structure
      actions:
        - List all directories
        - Count files per directory
        - Identify purpose from names

    3_extract_metadata:
      description: Get project metadata
      sources:
        - package.json (name, version, description, dependencies)
        - README.md (description, usage)
        - project_manifest.json (if exists)

    4_identify_features:
      description: Detect main features
      methods:
        - Keyword scanning in file names
        - Pattern matching in code
        - Directory structure analysis

    5_map_components:
      description: Catalog UI components
      methods:
        - Scan component directories
        - Extract props from TypeScript
        - Find usage patterns

    6_document_apis:
      description: Document API endpoints
      methods:
        - Scan API routes
        - Extract request/response schemas
        - Find authentication requirements

    7_model_data:
      description: Document data models
      methods:
        - Parse Prisma schema
        - Extract TypeORM entities
        - Find Mongoose schemas

    8_collect_terms:
      description: Build glossary
      methods:
        - Extract acronyms
        - Find domain terms
        - Look for jargon in comments