Metadata-Version: 2.4
Name: sourcecode
Version: 0.2.0
Summary: Genera un mapa de contexto estructurado de proyectos de software para agentes IA
License: MIT
Requires-Python: >=3.9
Requires-Dist: pathspec>=1.0
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.24
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Description-Content-Type: text/markdown

# sourcecode

`sourcecode` generates a structured project context map so an agent can quickly understand a repository's stack, entry points, and overall shape.

## Installation

```bash
pip install sourcecode
```

Requires Python `3.9+`.

## Quick Start

Analyze the current directory as JSON:

```bash
sourcecode .
```

Generate a compact view for prompts or handoff:

```bash
sourcecode --compact .
```

Analyze another directory and write YAML to a file:

```bash
sourcecode --format yaml --output sourcecode.yaml /path/to/project
```

Show the version:

```bash
sourcecode --version
```

Main options:

- `--format json|yaml`: output format.
- `--output PATH`: write to a file instead of `stdout`.
- `--compact`: return a reduced view with `schema_version`, `project_type`, `stacks`, `entry_points`, and `file_tree_depth1`.
- `--depth INTEGER`: maximum file tree depth.
- `--no-redact`: disable secret redaction.

## What It Detects

- Stacks: Node.js, Python, Go, Rust, Java, PHP, Ruby, and Dart.
- Frameworks associated with each stack when enough signals are present.
- `project_type`: `webapp`, `api`, `library`, `cli`, `fullstack`, `monorepo`, or `unknown`.
- Relevant `entry_points`, such as `main.py`, `cmd/api/main.go`, or `app/page.tsx`.
- Workspace roots in multi-stack or monorepo repositories.

## Compact Example

Real output from a Next.js fixture:

```json
{
  "schema_version": "1.0",
  "project_type": "webapp",
  "stacks": [
    {
      "stack": "nodejs",
      "detection_method": "manifest",
      "confidence": "high",
      "frameworks": [
        { "name": "Next.js", "source": "package.json" },
        { "name": "React", "source": "package.json" }
      ],
      "package_manager": "pnpm",
      "manifests": ["package.json"],
      "primary": true,
      "root": ".",
      "workspace": null,
      "signals": [
        "manifest:package.json",
        "framework:Next.js",
        "framework:React",
        "package_manager:pnpm",
        "entry:app/page.tsx"
      ]
    }
  ],
  "entry_points": [
    {
      "path": "app/page.tsx",
      "stack": "nodejs",
      "kind": "web",
      "source": "package.json"
    }
  ],
  "file_tree_depth1": {
    "pnpm-lock.yaml": null,
    "package.json": null,
    "app": {}
  }
}
```

## Monorepo Example

In a monorepo, each stack includes its own `root` and `workspace`, and one of them is marked as `primary`.

```json
{
  "project_type": "monorepo",
  "stacks": [
    {
      "stack": "nodejs",
      "primary": true,
      "root": "apps/web",
      "workspace": "apps/web"
    },
    {
      "stack": "python",
      "primary": false,
      "root": "packages/api",
      "workspace": "packages/api"
    }
  ],
  "entry_points": [
    { "path": "apps/web/app/page.tsx", "stack": "nodejs", "kind": "web" },
    { "path": "packages/api/main.py", "stack": "python", "kind": "cli" }
  ]
}
```

## Output

The full schema includes:

- `metadata`: schema version, timestamp, `sourcecode` version, and analyzed path.
- `file_tree`: repository tree where `null` represents a file and an object represents a directory.
- `stacks`: stack detections with confidence, frameworks, manifests, `primary`, `root`, `workspace`, and `signals`.
- `project_type`: overall project classification.
- `entry_points`: detected entry points by stack.

Detailed reference: [docs/schema.md](/Users/user/Documents/workspace/atlas/atlas-cli/docs/schema.md).

## Development

Editable install with development dependencies:

```bash
pip install -e ".[dev]"
```

Local validation:

```bash
ruff check src tests
mypy src
pytest -q
```
