# `@use` declarations

## Usage

`@use` imports namespaces/ops or pipelines from other `.ops` files so call sites can invoke them with short names.

```ops
@use git
@use std.log as log
@use ./validation as validate
@use ./deploy as deploy
@use ./deprecated/slack
@use ./release
@use .forgejo/workflows/validation
```

**Validation:** diff compiled bash output against a known-good baseline after changing `@use` lines.

## Grammar

```
UseDecl         = '@use' Path ('as' Alias)?
Path            = IDENT ('.' IDENT)* ('/' IDENT)* ('.ops')?
Alias           = IDENT
```

**Aliases:** `[a-zA-Z_][a-zA-Z0-9_-]*` (identifier regex for `as` names).

## IR representation

Canonical import shape lives in [ir_schema](../ir_schema.md) and [sources-and-provenance](../ir/sources-and-provenance.md).

```json
{
  "role": "file",
  "payload": [
    { "role": "import", "name": "git", "payload": "registry:git" },
    { "role": "import", "name": "validate", "payload": "file:validation.ops" }
  ]
}
```

- Dotted paths contribute to operation/namespace imports.
- Paths containing `/` contribute to pipeline source imports.

## Implementation

**Tier 2 — Minimal parser**

| Area | Responsibility |
|------|----------------|
| `ast.rs` | `File`, `TopLevel::Use` |
| `parser.rs` | Top-level dispatch; `@use` with optional `as` |
| `ir.rs` | `IrFile` imports with namespace, source ID, and provenance |
| `lower.rs` | Slash vs dotted path classification; alias mapping |

## Design decisions

- **Cross-file:** `@use my/pipeline/a` means `a()` can invoke that pipeline’s **main** group.
- **Path shape:** `/` in the path → pipeline source import. Dotted identifier chain → namespace/op import.
- **Optional `as`:** Allows shorter references at call sites without renaming the source.

## Caveats

- Classification depends on path syntax (slashes vs dots); mixed or ambiguous paths need clear parser rules in `lower.rs`.

## Open questions

_None captured for this feature._
