1. Introduction

1.1 Purpose

This document describes the detailed design and technical flow for a new feature in TurboRepo: package-level restrictions via a package_restrictions mapping in turbo.json. The goal is to allow repository owners to define which apps or packages may import or depend on specific internal packages, preventing accidental or unauthorized usage in large monorepos.

1.2 Scope

• Design and implementation details
• JSON configuration schema
• Validation and enforcement flow
• CLI and API changes
• Error reporting and developer feedback
• Performance considerations

1.3 Audience

• TurboRepo core team
• Tooling/DevOps engineers
• Monorepo maintainers and architects

2. Background & Motivation

• Problem: In large monorepos, developers sometimes import internal or sensitive packages by mistake. Without guardrails, unintended dependencies can slip into build artifacts or production deployments.
• Current Behavior: All workspace packages are accessible by default through workspaces:*. No restriction mechanism exists.
• Proposed Solution: Introduce a package_restrictions section in turbo.json where each package lists include and except entries to grant or deny usage by named workspaces.

3. Configuration Schema

{
  "package_restrictions": {
    "<package-alias>": {
      "include": ["<allowed-app-or-package>"],
      "except": ["<denied-app-or-package>"]
    }
    // ... more packages
  }
}

• package-alias: The name field from that package’s package.json.
• include: Whitelist: only these workspaces may depend on the package. If omitted, defaults to all.
• except: Blacklist: these workspaces may not depend on the package.

Rules:

1. If both include and except are present, include is evaluated first, then except.
2. Undefined / Missing include means all allowed (by default).
3. Empty include means none allowed.
4. If a package is not listed, it remains unrestricted.

4. Technical Design

4.1 Integration Point

• Modify TurboRepo’s dependency resolution step before build graph creation.
• Add a new validator that inspects each declared dependency edge.

4.2 Data Structures

• In-Memory Map: Load turbo.json at startup into a JS object:

  type Restrictions = Record<string, {
    include?: string[];
    except?: string[];
  }>;
  const restrictions: Restrictions;

• Workspace Index: Map workspace name → package path.

4.3 Validation Algorithm

1. Load: Read and parse turbo.json, merge with defaults.

2. Traverse Dependencies: For each workspace A, for each declared dependency on package P:

   • If P in restrictions:

     • If restrictions[P].include exists and A not in it → reject
     • Else if restrictions[P].except exists and A in it → reject

3. Outcome:

   • Allowed: proceed normally
   • Rejected: throw an error with actionable guidance

4.4 Error Handling & Messaging

• Error Format:

  TURBO_ERROR: Workspace "app-frontend" is not permitted to depend on "internal-auth".
  Allowed: "[api-server, admin-dashboard]"
  Denied: "[app-frontend]"
  See docs: https://turbo.build/docs/package-restrictions
  

• Exit Code: Non-zero (e.g. 1) to fail build.

• Suggestion: Path to turbo.json snippet highlighting the policy.

4.5 CLI & Flags

• No new CLI commands: existing turbo run build and turbo dev will automatically enforce.
• Flag: --skip-package-restrictions for advanced users to bypass checks.

4.6 Caching & Performance

• Cache Key: Include hash of turbo.json in pipeline cache to recalc only when config changes.
• Complexity: O(E) where E = number of dependency edges. Acceptable even for large monorepos.

4.7 Documentation & Developer Experience

• Update CLI help: mention package_restrictions in --help output.
• Add a new section in TurboRepo docs detailing configuration, examples, error codes.

5. Flow Diagram

flowchart LR
  A[Start turbo run] --> B[Load turbo.json]
  B --> C[Parse package_restrictions]
  C --> D[Build dependency graph]
  D --> E[For each edge: validateRestrictions]
  E -->|allowed| F[Continue build]
  E -->|rejected| G[Report error + exit]
  F --> H[Execute tasks]
  G --> I[Abort]

Product Requirements Document (PRD)

PRD 1. Overview

Feature Name: Package Restrictions Enforcement

Objective: Empower monorepo maintainers to enforce architectural boundaries by restricting which workspaces can depend on specified packages.

PRD 2. Key Stakeholders

• Product Manager: Defines scope, priorities
• Engineering Team: Designs and implements feature
• DevOps/Platform Engineers: Integrate into pipelines
• End Users: Monorepo maintainers

PRD 3. User Stories

PRD 4. Functional Requirements

1. Config Parsing: CLI loads package_restrictions from turbo.json.
2. Validation: All declared dependencies are checked against restrictions.
3. Error Reporting: Provide actionable errors on violation.
4. Skip Flag: --skip-package-restrictions disables checks.

PRD 5. Non-Functional Requirements

• Performance: Validation overhead < 5% of total build time for 1,000 workspaces.
• Reliability: 100% accuracy in policy enforcement.
• Usability: Errors should point to relevant config section.

PRD 6. Acceptance Criteria

• Config schema validated against JSON schema.
• Unit tests cover > 90% of validator code.
• Integration tests ensure disallowed imports fail the build.
• Documentation published.
• Demo performed with sample monorepo.

PRD 7. Timeline & Milestones