dotmd-parser 0.2.0__tar.gz → 0.2.1__tar.gz

{dotmd_parser-0.2.0/src/dotmd_parser.egg-info → dotmd_parser-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotmd-parser
-Version: 0.2.0
+Version: 0.2.1
 Summary: Dependency graph parser for .md skill files — parse @include/@delegate/@ref directives, build graphs, and resolve templates for AI agent prompt engineering
 Author: dotmd-projects
 License-Expression: MIT
@@ -39,7 +39,7 @@ Dependency graph parser for `.md` skill files — built for AI agent prompt engi
 
 ## Why dotmd-parser?
 
-As AI agent projects grow, `SKILL.md` files start referencing each other via `@include` and `@delegate` directives. Without tooling, you're left manually tracing dependencies to answer basic questions:
+As AI agent projects grow, `.md` files start referencing each other via `@include`, `@delegate`, and `@ref` directives. Without tooling, you're left manually tracing dependencies to answer basic questions:
 
 - *"Which files break if I edit `shared/role.md`?"*
 - *"Is there a circular reference hiding in my skill tree?"*
@@ -51,7 +51,7 @@ As AI agent projects grow, `SKILL.md` files start referencing each other via `@i
 
 | Capability | Manual / grep | dotmd-parser |
 |---|---|---|
-| Find `@include` / `@delegate` references | `grep -r "@include"` — flat list, no context | Structured graph with node types and edge metadata |
+| Find `@include` / `@delegate` / `@ref` references | `grep -r "@include"` — flat list, no context | Structured graph with node types and edge metadata |
 | Detect circular references | Hope you notice before the agent loops | Automatic detection with full cycle path in warnings |
 | Reverse dependency ("what breaks?") | Manually trace every file | `dependents_of(graph, "shared/role.md")` — one call |
 | Expand `@include` to final text | Copy-paste by hand | `resolve("SKILL.md", variables={...})` — recursive expansion |
@@ -92,8 +92,32 @@ Returns:
 }
 ```
 
+**Custom node type mapping:**
+
+By default, node types are inferred from path keywords (`agent`, `shared`, `prompt`, `reference`, `asset`, `template`). You can override this with the `type_map` parameter:
+
+```python
+graph = build_graph("./my-skill/", type_map=[
+    ("helper", "utility"),
+    ("core", "foundation"),
+])
+```
+
+**deps.yml support:**
+
+If a `deps.yml` file exists in the root directory, its dependencies are automatically merged into the graph:
+
+```yaml
+- path: agents/planner.md
+  includes:
+    - shared/role.md
+    - shared/tools.md
+```
+
 ### resolve — Expand @include directives
 
+Recursively expands `@include` directives into final text. `@delegate` and `@ref` lines are left as-is.
+
 ```python
 result = resolve("./prompts/main.md", variables={"name": "Alice"})
 
@@ -113,20 +137,36 @@ affected = dependents_of(graph, "/abs/path/to/shared/role.md")
 
 ```python
 print(summary(graph))
-# Nodes: 5  (agent:1, shared:2, skill:1, reference:1)
-# Edges: 4  (include:3, read-ref:1)
+# Nodes: 5  (agent:1, prompt:1, shared:2, skill:1)
+# Edges: 4  (include:2, ref:1, read-ref:1)
 # Warnings: 0
+# Placeholders: name, role
 ```
 
 ## Supported Directives
 
-| Directive | Description |
+| Directive | Edge type | Expanded by `resolve()`? | Description |
+|---|---|---|---|
+| `@include path/to/file.md` | `include` | Yes | Inline expansion — file content is inserted at this position |
+| `@delegate path/to/agent.md` | `delegate` | No | Agent delegation — recorded in graph, left as-is in output |
+| `@delegate path/to/agent.md --parallel` | `delegate` | No | Parallel delegation with `--parallel` flag |
+| `@ref path/to/file.md` | `ref` | No | Runtime reference — recorded in graph, left as-is in output |
+| `` Read `path/to/file.md` `` | `read-ref` | No | Legacy runtime reference (same as `@ref`, kept for backward compatibility) |
+
+## Utility Functions
+
+Lower-level parsing functions are also exported for custom use:
+
+```python
+from dotmd_parser import parse_directives, parse_read_refs, parse_placeholders, parse_deps_yml
+```
+
+| Function | Description |
 |---|---|
-| `@include path/to/file.md` | Inline expansion — file content is inserted at this position |
-| `@delegate path/to/agent.md` | Agent delegation — recorded in graph but not expanded |
-| `@delegate path/to/agent.md --parallel` | Parallel delegation with `--parallel` flag |
-| `@ref path/to/file.md` | Runtime reference — recorded in graph but not expanded |
-| `` Read `path/to/file.md` `` | Legacy runtime reference — same behavior as `@ref` (kept for backward compatibility) |
+| `parse_directives(content)` | Extract `@include` / `@delegate` / `@ref` directives from text |
+| `parse_read_refs(content)` | Extract legacy `Read`/`See`/list-style `.md` references (deduplicated) |
+| `parse_placeholders(content)` | Extract `{{variable}}` placeholder names (deduplicated) |
+| `parse_deps_yml(content)` | Parse `deps.yml` text into `{path: [includes]}` dict (no PyYAML required) |
 
 ## CLI
 
@@ -138,6 +178,8 @@ dotmd-parser ./my-skill/
 python -m dotmd_parser.parser ./my-skill/
 ```
 
+Outputs a human-readable summary followed by the full JSON graph.
+
 ## Development
 
 ```bash

{dotmd_parser-0.2.0 → dotmd_parser-0.2.1}/README.md

@@ -12,7 +12,7 @@ Dependency graph parser for `.md` skill files — built for AI agent prompt engi
 
 ## Why dotmd-parser?
 
-As AI agent projects grow, `SKILL.md` files start referencing each other via `@include` and `@delegate` directives. Without tooling, you're left manually tracing dependencies to answer basic questions:
+As AI agent projects grow, `.md` files start referencing each other via `@include`, `@delegate`, and `@ref` directives. Without tooling, you're left manually tracing dependencies to answer basic questions:
 
 - *"Which files break if I edit `shared/role.md`?"*
 - *"Is there a circular reference hiding in my skill tree?"*
@@ -24,7 +24,7 @@ As AI agent projects grow, `SKILL.md` files start referencing each other via `@i
 
 | Capability | Manual / grep | dotmd-parser |
 |---|---|---|
-| Find `@include` / `@delegate` references | `grep -r "@include"` — flat list, no context | Structured graph with node types and edge metadata |
+| Find `@include` / `@delegate` / `@ref` references | `grep -r "@include"` — flat list, no context | Structured graph with node types and edge metadata |
 | Detect circular references | Hope you notice before the agent loops | Automatic detection with full cycle path in warnings |
 | Reverse dependency ("what breaks?") | Manually trace every file | `dependents_of(graph, "shared/role.md")` — one call |
 | Expand `@include` to final text | Copy-paste by hand | `resolve("SKILL.md", variables={...})` — recursive expansion |
@@ -65,8 +65,32 @@ Returns:
 }
 ```
 
+**Custom node type mapping:**
+
+By default, node types are inferred from path keywords (`agent`, `shared`, `prompt`, `reference`, `asset`, `template`). You can override this with the `type_map` parameter:
+
+```python
+graph = build_graph("./my-skill/", type_map=[
+    ("helper", "utility"),
+    ("core", "foundation"),
+])
+```
+
+**deps.yml support:**
+
+If a `deps.yml` file exists in the root directory, its dependencies are automatically merged into the graph:
+
+```yaml
+- path: agents/planner.md
+  includes:
+    - shared/role.md
+    - shared/tools.md
+```
+
 ### resolve — Expand @include directives
 
+Recursively expands `@include` directives into final text. `@delegate` and `@ref` lines are left as-is.
+
 ```python
 result = resolve("./prompts/main.md", variables={"name": "Alice"})
 
@@ -86,20 +110,36 @@ affected = dependents_of(graph, "/abs/path/to/shared/role.md")
 
 ```python
 print(summary(graph))
-# Nodes: 5  (agent:1, shared:2, skill:1, reference:1)
-# Edges: 4  (include:3, read-ref:1)
+# Nodes: 5  (agent:1, prompt:1, shared:2, skill:1)
+# Edges: 4  (include:2, ref:1, read-ref:1)
 # Warnings: 0
+# Placeholders: name, role
 ```
 
 ## Supported Directives
 
-| Directive | Description |
+| Directive | Edge type | Expanded by `resolve()`? | Description |
+|---|---|---|---|
+| `@include path/to/file.md` | `include` | Yes | Inline expansion — file content is inserted at this position |
+| `@delegate path/to/agent.md` | `delegate` | No | Agent delegation — recorded in graph, left as-is in output |
+| `@delegate path/to/agent.md --parallel` | `delegate` | No | Parallel delegation with `--parallel` flag |
+| `@ref path/to/file.md` | `ref` | No | Runtime reference — recorded in graph, left as-is in output |
+| `` Read `path/to/file.md` `` | `read-ref` | No | Legacy runtime reference (same as `@ref`, kept for backward compatibility) |
+
+## Utility Functions
+
+Lower-level parsing functions are also exported for custom use:
+
+```python
+from dotmd_parser import parse_directives, parse_read_refs, parse_placeholders, parse_deps_yml
+```
+
+| Function | Description |
 |---|---|
-| `@include path/to/file.md` | Inline expansion — file content is inserted at this position |
-| `@delegate path/to/agent.md` | Agent delegation — recorded in graph but not expanded |
-| `@delegate path/to/agent.md --parallel` | Parallel delegation with `--parallel` flag |
-| `@ref path/to/file.md` | Runtime reference — recorded in graph but not expanded |
-| `` Read `path/to/file.md` `` | Legacy runtime reference — same behavior as `@ref` (kept for backward compatibility) |
+| `parse_directives(content)` | Extract `@include` / `@delegate` / `@ref` directives from text |
+| `parse_read_refs(content)` | Extract legacy `Read`/`See`/list-style `.md` references (deduplicated) |
+| `parse_placeholders(content)` | Extract `{{variable}}` placeholder names (deduplicated) |
+| `parse_deps_yml(content)` | Parse `deps.yml` text into `{path: [includes]}` dict (no PyYAML required) |
 
 ## CLI
 
@@ -111,6 +151,8 @@ dotmd-parser ./my-skill/
 python -m dotmd_parser.parser ./my-skill/
 ```
 
+Outputs a human-readable summary followed by the full JSON graph.
+
 ## Development
 
 ```bash

{dotmd_parser-0.2.0 → dotmd_parser-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dotmd-parser"
-version = "0.2.0"
+version = "0.2.1"
 description = "Dependency graph parser for .md skill files — parse @include/@delegate/@ref directives, build graphs, and resolve templates for AI agent prompt engineering"
 requires-python = ">=3.10"
 license = "MIT"

{dotmd_parser-0.2.0 → dotmd_parser-0.2.1}/src/dotmd_parser/__init__.py

@@ -8,7 +8,7 @@ API:
     from dotmd_parser import build_graph, resolve, dependents_of, summary
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 from dotmd_parser.parser import (
     build_graph,

{dotmd_parser-0.2.0 → dotmd_parser-0.2.1/src/dotmd_parser.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotmd-parser
-Version: 0.2.0
+Version: 0.2.1
 Summary: Dependency graph parser for .md skill files — parse @include/@delegate/@ref directives, build graphs, and resolve templates for AI agent prompt engineering
 Author: dotmd-projects
 License-Expression: MIT
@@ -39,7 +39,7 @@ Dependency graph parser for `.md` skill files — built for AI agent prompt engi
 
 ## Why dotmd-parser?
 
-As AI agent projects grow, `SKILL.md` files start referencing each other via `@include` and `@delegate` directives. Without tooling, you're left manually tracing dependencies to answer basic questions:
+As AI agent projects grow, `.md` files start referencing each other via `@include`, `@delegate`, and `@ref` directives. Without tooling, you're left manually tracing dependencies to answer basic questions:
 
 - *"Which files break if I edit `shared/role.md`?"*
 - *"Is there a circular reference hiding in my skill tree?"*
@@ -51,7 +51,7 @@ As AI agent projects grow, `SKILL.md` files start referencing each other via `@i
 
 | Capability | Manual / grep | dotmd-parser |
 |---|---|---|
-| Find `@include` / `@delegate` references | `grep -r "@include"` — flat list, no context | Structured graph with node types and edge metadata |
+| Find `@include` / `@delegate` / `@ref` references | `grep -r "@include"` — flat list, no context | Structured graph with node types and edge metadata |
 | Detect circular references | Hope you notice before the agent loops | Automatic detection with full cycle path in warnings |
 | Reverse dependency ("what breaks?") | Manually trace every file | `dependents_of(graph, "shared/role.md")` — one call |
 | Expand `@include` to final text | Copy-paste by hand | `resolve("SKILL.md", variables={...})` — recursive expansion |
@@ -92,8 +92,32 @@ Returns:
 }
 ```
 
+**Custom node type mapping:**
+
+By default, node types are inferred from path keywords (`agent`, `shared`, `prompt`, `reference`, `asset`, `template`). You can override this with the `type_map` parameter:
+
+```python
+graph = build_graph("./my-skill/", type_map=[
+    ("helper", "utility"),
+    ("core", "foundation"),
+])
+```
+
+**deps.yml support:**
+
+If a `deps.yml` file exists in the root directory, its dependencies are automatically merged into the graph:
+
+```yaml
+- path: agents/planner.md
+  includes:
+    - shared/role.md
+    - shared/tools.md
+```
+
 ### resolve — Expand @include directives
 
+Recursively expands `@include` directives into final text. `@delegate` and `@ref` lines are left as-is.
+
 ```python
 result = resolve("./prompts/main.md", variables={"name": "Alice"})
 
@@ -113,20 +137,36 @@ affected = dependents_of(graph, "/abs/path/to/shared/role.md")
 
 ```python
 print(summary(graph))
-# Nodes: 5  (agent:1, shared:2, skill:1, reference:1)
-# Edges: 4  (include:3, read-ref:1)
+# Nodes: 5  (agent:1, prompt:1, shared:2, skill:1)
+# Edges: 4  (include:2, ref:1, read-ref:1)
 # Warnings: 0
+# Placeholders: name, role
 ```
 
 ## Supported Directives
 
-| Directive | Description |
+| Directive | Edge type | Expanded by `resolve()`? | Description |
+|---|---|---|---|
+| `@include path/to/file.md` | `include` | Yes | Inline expansion — file content is inserted at this position |
+| `@delegate path/to/agent.md` | `delegate` | No | Agent delegation — recorded in graph, left as-is in output |
+| `@delegate path/to/agent.md --parallel` | `delegate` | No | Parallel delegation with `--parallel` flag |
+| `@ref path/to/file.md` | `ref` | No | Runtime reference — recorded in graph, left as-is in output |
+| `` Read `path/to/file.md` `` | `read-ref` | No | Legacy runtime reference (same as `@ref`, kept for backward compatibility) |
+
+## Utility Functions
+
+Lower-level parsing functions are also exported for custom use:
+
+```python
+from dotmd_parser import parse_directives, parse_read_refs, parse_placeholders, parse_deps_yml
+```
+
+| Function | Description |
 |---|---|
-| `@include path/to/file.md` | Inline expansion — file content is inserted at this position |
-| `@delegate path/to/agent.md` | Agent delegation — recorded in graph but not expanded |
-| `@delegate path/to/agent.md --parallel` | Parallel delegation with `--parallel` flag |
-| `@ref path/to/file.md` | Runtime reference — recorded in graph but not expanded |
-| `` Read `path/to/file.md` `` | Legacy runtime reference — same behavior as `@ref` (kept for backward compatibility) |
+| `parse_directives(content)` | Extract `@include` / `@delegate` / `@ref` directives from text |
+| `parse_read_refs(content)` | Extract legacy `Read`/`See`/list-style `.md` references (deduplicated) |
+| `parse_placeholders(content)` | Extract `{{variable}}` placeholder names (deduplicated) |
+| `parse_deps_yml(content)` | Parse `deps.yml` text into `{path: [includes]}` dict (no PyYAML required) |
 
 ## CLI
 
@@ -138,6 +178,8 @@ dotmd-parser ./my-skill/
 python -m dotmd_parser.parser ./my-skill/
 ```
 
+Outputs a human-readable summary followed by the full JSON graph.
+
 ## Development
 
 ```bash