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

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: dotmd-parser
-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
+Version: 0.5.0
+Summary: Dependency graph parser and AI analyzer for .md skill files — parse @include/@delegate/@ref directives, build graphs, resolve templates, and detect implicit dependencies via Claude for AI agent prompt engineering
 Author: dotmd-projects
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/dotmd-projects/dotmd-parser
@@ -57,6 +57,8 @@ As AI agent projects grow, `.md` files start referencing each other via `@includ
 | Expand `@include` to final text | Copy-paste by hand | `resolve("SKILL.md", variables={...})` — recursive expansion |
 | Find unresolved `{{variables}}` | `grep "{{" *.md` — noisy, no dedup | Deduplicated list per node and after expansion |
 | Missing file detection | Runtime failure | Warnings at parse time with exact paths |
+| Detect **implicit** deps (no directives yet) | Read every file, draw by hand | `analyze` subcommand asks Claude, emits `@include` / `deps.yml` |
+| Feed Claude Code with compact context | Read 20 files × 5 KB each | `digest` outputs one ~2 KB summary; `.claude/dotmd-index.json` cache |
 
 ## Installation
 
@@ -170,15 +172,136 @@ from dotmd_parser import parse_directives, parse_read_refs, parse_placeholders,
 
 ## CLI
 
+`dotmd-parser` ships with sub-commands tuned for Claude Code and CI use. Running `dotmd-parser <path>` with no sub-command still works and falls through to `show` for backward compatibility.
+
+| Command | Purpose |
+|---|---|
+| `dotmd-parser inventory <path>` | **API-free**: extension counts, markdown/binary ratio, largest files |
+| `dotmd-parser index <path>` | Build and save `.claude/dotmd-index.json` |
+| `dotmd-parser index <path> --scope <subdir>` | Incrementally re-index one subfolder, merge into the existing index |
+| `dotmd-parser check <path>` | Exit non-zero on cycles / missing refs (CI-friendly) |
+| `dotmd-parser affects <path> <file>` | Reverse dependencies of `<file>` |
+| `dotmd-parser deps <path> <file>` | Direct dependencies of `<file>` |
+| `dotmd-parser digest <path>` | Token-efficient text summary for LLM context |
+| `dotmd-parser tree <path>` | ASCII dependency tree |
+| `dotmd-parser resolve <file> [--var k=v]` | Recursively expand `@include` |
+| `dotmd-parser analyze <path>` | AI dependency detection (requires `ANTHROPIC_API_KEY`) |
+| `dotmd-parser analyze <path> --dry-run` | **API-free**: estimate tokens and USD cost |
+| `dotmd-parser analyze <path> --plan` | **API-free**: emit a host-agent prompt pack for Claude Code to execute |
+| `dotmd-parser analyze <path> --apply-from <json>` | Apply a pre-computed analysis JSON |
+| `dotmd-parser show <path>` | Summary + full JSON graph (legacy default) |
+
+```bash
+# Typical Claude Code workflow
+dotmd-parser inventory ./my-skill/       # start here if you've never seen the folder
+dotmd-parser index ./my-skill/           # one-off; cached until files change
+dotmd-parser digest ./my-skill/          # compact summary for the LLM
+dotmd-parser affects ./my-skill/ shared/role.md
+```
+
+## `analyze` — AI-assisted dependency detection
+
+Use when a folder of markdown has **no explicit directives yet**. `analyze`
+asks Claude to infer dependencies and can apply the result in one step:
+
 ```bash
-# Installed as a command
-dotmd-parser ./my-skill/
+export ANTHROPIC_API_KEY=...   # or put it in ./.env
+
+dotmd-parser analyze ./docs/              # runs the proposal (uses API)
+dotmd-parser analyze ./docs/ --apply      # inject @include, write deps.yml
+dotmd-parser analyze ./docs/ --json       # machine-readable
+dotmd-parser analyze ./docs/ --ext md --ext pdf --ext docx
+```
+
+### No-API-key workflows
+
+```bash
+# Estimate cost before spending any API credit
+dotmd-parser analyze ./docs/ --dry-run
+
+# Delegate the analysis to Claude Code itself — no API key needed
+dotmd-parser analyze ./docs/ --plan > plan.md
+#   1. Claude Code reads plan.md and executes the task locally
+#   2. It writes the result to analysis.json
+#   3. Apply it:
+dotmd-parser analyze ./docs/ --apply-from analysis.json
+```
+
+- Text files (`.md`, `.txt`, etc.) get `@include` lines prepended.
+- Binary sources (`.pdf`, `.docx`) are recorded in `deps.yml` — they can't
+  be edited in-place, so the parser reads them from there.
+- PDF / DOCX support is optional: `pip install pdfplumber python-docx`.
+- Re-run with `--apply` over time as the repo grows — existing directives
+  are preserved.
+
+The bundled prompt lives at
+`src/dotmd_parser/templates/prompts/analyze-dependencies.md` and is shipped
+inside the wheel; no network access is needed except for the Claude API
+call itself.
+
+### Programmatic use
+
+```python
+from dotmd_parser import analyze_dependencies, apply_analysis
 
-# Or via Python module
-python -m dotmd_parser.parser ./my-skill/
+proposal = analyze_dependencies("./docs/")
+print(proposal["edges"])
+apply_analysis("./docs/", proposal)
+```
+
+For offline tests, pass a `caller=...` kwarg that returns a stub JSON string.
+
+## Claude Code Skill integration
+
+A ready-to-use Claude Code Skill is bundled with the package at
+`src/dotmd_parser/templates/SKILL.md`. Three install paths:
+
+```bash
+# via pip — installs the CLI and drops SKILL.md into the current project
+pip install dotmd-parser
+dotmd-parser init .
+
+# via Release archive — no pip required
+mkdir -p .claude/skills
+curl -L https://github.com/dotmd-projects/dotmd-parser/releases/latest/download/skill.tar.gz \
+  | tar -xz -C .claude/skills/
+
+# manual
+cp src/dotmd_parser/templates/SKILL.md \
+   /path/to/project/.claude/skills/dotmd-parser/
+```
+
+Once installed, Claude will consult the skill whenever it encounters
+`SKILL.md`, `deps.yml`, a `.claude/skills/` tree, or is asked about
+dependencies of a markdown file.
+
+**Why this saves tokens.** Without the skill, Claude typically `grep -r`s
+for `@include`/`@ref` and `cat`s every referenced file to trace a graph.
+With the skill it reads `.claude/dotmd-index.json` (compact, relative paths,
+first-paragraph descriptions) or the `digest` output once, then queries
+`affects` / `deps` by name — never touching the raw markdown until an edit
+is actually needed.
+
+### Auto-refresh via Hook (optional)
+
+Add to `~/.claude/settings.json` to keep `.claude/dotmd-index.json` fresh
+after every markdown edit:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "command": "dotmd-parser index \"$CLAUDE_PROJECT_DIR\" >/dev/null 2>&1 || true"
+      }
+    ]
+  }
+}
 ```
 
-Outputs a human-readable summary followed by the full JSON graph.
+The command is idempotent (SHA-256 cache) and exits fast when nothing
+changed.
 
 ## Development
 

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

@@ -30,6 +30,8 @@ As AI agent projects grow, `.md` files start referencing each other via `@includ
 | Expand `@include` to final text | Copy-paste by hand | `resolve("SKILL.md", variables={...})` — recursive expansion |
 | Find unresolved `{{variables}}` | `grep "{{" *.md` — noisy, no dedup | Deduplicated list per node and after expansion |
 | Missing file detection | Runtime failure | Warnings at parse time with exact paths |
+| Detect **implicit** deps (no directives yet) | Read every file, draw by hand | `analyze` subcommand asks Claude, emits `@include` / `deps.yml` |
+| Feed Claude Code with compact context | Read 20 files × 5 KB each | `digest` outputs one ~2 KB summary; `.claude/dotmd-index.json` cache |
 
 ## Installation
 
@@ -143,15 +145,136 @@ from dotmd_parser import parse_directives, parse_read_refs, parse_placeholders,
 
 ## CLI
 
+`dotmd-parser` ships with sub-commands tuned for Claude Code and CI use. Running `dotmd-parser <path>` with no sub-command still works and falls through to `show` for backward compatibility.
+
+| Command | Purpose |
+|---|---|
+| `dotmd-parser inventory <path>` | **API-free**: extension counts, markdown/binary ratio, largest files |
+| `dotmd-parser index <path>` | Build and save `.claude/dotmd-index.json` |
+| `dotmd-parser index <path> --scope <subdir>` | Incrementally re-index one subfolder, merge into the existing index |
+| `dotmd-parser check <path>` | Exit non-zero on cycles / missing refs (CI-friendly) |
+| `dotmd-parser affects <path> <file>` | Reverse dependencies of `<file>` |
+| `dotmd-parser deps <path> <file>` | Direct dependencies of `<file>` |
+| `dotmd-parser digest <path>` | Token-efficient text summary for LLM context |
+| `dotmd-parser tree <path>` | ASCII dependency tree |
+| `dotmd-parser resolve <file> [--var k=v]` | Recursively expand `@include` |
+| `dotmd-parser analyze <path>` | AI dependency detection (requires `ANTHROPIC_API_KEY`) |
+| `dotmd-parser analyze <path> --dry-run` | **API-free**: estimate tokens and USD cost |
+| `dotmd-parser analyze <path> --plan` | **API-free**: emit a host-agent prompt pack for Claude Code to execute |
+| `dotmd-parser analyze <path> --apply-from <json>` | Apply a pre-computed analysis JSON |
+| `dotmd-parser show <path>` | Summary + full JSON graph (legacy default) |
+
+```bash
+# Typical Claude Code workflow
+dotmd-parser inventory ./my-skill/       # start here if you've never seen the folder
+dotmd-parser index ./my-skill/           # one-off; cached until files change
+dotmd-parser digest ./my-skill/          # compact summary for the LLM
+dotmd-parser affects ./my-skill/ shared/role.md
+```
+
+## `analyze` — AI-assisted dependency detection
+
+Use when a folder of markdown has **no explicit directives yet**. `analyze`
+asks Claude to infer dependencies and can apply the result in one step:
+
 ```bash
-# Installed as a command
-dotmd-parser ./my-skill/
+export ANTHROPIC_API_KEY=...   # or put it in ./.env
+
+dotmd-parser analyze ./docs/              # runs the proposal (uses API)
+dotmd-parser analyze ./docs/ --apply      # inject @include, write deps.yml
+dotmd-parser analyze ./docs/ --json       # machine-readable
+dotmd-parser analyze ./docs/ --ext md --ext pdf --ext docx
+```
+
+### No-API-key workflows
+
+```bash
+# Estimate cost before spending any API credit
+dotmd-parser analyze ./docs/ --dry-run
+
+# Delegate the analysis to Claude Code itself — no API key needed
+dotmd-parser analyze ./docs/ --plan > plan.md
+#   1. Claude Code reads plan.md and executes the task locally
+#   2. It writes the result to analysis.json
+#   3. Apply it:
+dotmd-parser analyze ./docs/ --apply-from analysis.json
+```
+
+- Text files (`.md`, `.txt`, etc.) get `@include` lines prepended.
+- Binary sources (`.pdf`, `.docx`) are recorded in `deps.yml` — they can't
+  be edited in-place, so the parser reads them from there.
+- PDF / DOCX support is optional: `pip install pdfplumber python-docx`.
+- Re-run with `--apply` over time as the repo grows — existing directives
+  are preserved.
+
+The bundled prompt lives at
+`src/dotmd_parser/templates/prompts/analyze-dependencies.md` and is shipped
+inside the wheel; no network access is needed except for the Claude API
+call itself.
+
+### Programmatic use
+
+```python
+from dotmd_parser import analyze_dependencies, apply_analysis
 
-# Or via Python module
-python -m dotmd_parser.parser ./my-skill/
+proposal = analyze_dependencies("./docs/")
+print(proposal["edges"])
+apply_analysis("./docs/", proposal)
+```
+
+For offline tests, pass a `caller=...` kwarg that returns a stub JSON string.
+
+## Claude Code Skill integration
+
+A ready-to-use Claude Code Skill is bundled with the package at
+`src/dotmd_parser/templates/SKILL.md`. Three install paths:
+
+```bash
+# via pip — installs the CLI and drops SKILL.md into the current project
+pip install dotmd-parser
+dotmd-parser init .
+
+# via Release archive — no pip required
+mkdir -p .claude/skills
+curl -L https://github.com/dotmd-projects/dotmd-parser/releases/latest/download/skill.tar.gz \
+  | tar -xz -C .claude/skills/
+
+# manual
+cp src/dotmd_parser/templates/SKILL.md \
+   /path/to/project/.claude/skills/dotmd-parser/
+```
+
+Once installed, Claude will consult the skill whenever it encounters
+`SKILL.md`, `deps.yml`, a `.claude/skills/` tree, or is asked about
+dependencies of a markdown file.
+
+**Why this saves tokens.** Without the skill, Claude typically `grep -r`s
+for `@include`/`@ref` and `cat`s every referenced file to trace a graph.
+With the skill it reads `.claude/dotmd-index.json` (compact, relative paths,
+first-paragraph descriptions) or the `digest` output once, then queries
+`affects` / `deps` by name — never touching the raw markdown until an edit
+is actually needed.
+
+### Auto-refresh via Hook (optional)
+
+Add to `~/.claude/settings.json` to keep `.claude/dotmd-index.json` fresh
+after every markdown edit:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "command": "dotmd-parser index \"$CLAUDE_PROJECT_DIR\" >/dev/null 2>&1 || true"
+      }
+    ]
+  }
+}
 ```
 
-Outputs a human-readable summary followed by the full JSON graph.
+The command is idempotent (SHA-256 cache) and exits fast when nothing
+changed.
 
 ## Development
 

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

@@ -1,7 +1,7 @@
 [project]
 name = "dotmd-parser"
-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"
+version = "0.5.0"
+description = "Dependency graph parser and AI analyzer for .md skill files — parse @include/@delegate/@ref directives, build graphs, resolve templates, and detect implicit dependencies via Claude for AI agent prompt engineering"
 requires-python = ">=3.10"
 license = "MIT"
 readme = "README.md"
@@ -50,5 +50,9 @@ build-backend = "setuptools.build_meta"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+"dotmd_parser.templates" = ["*.md"]
+"dotmd_parser.templates.prompts" = ["*.md"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]

dotmd_parser-0.5.0/src/dotmd_parser/__init__.py

@@ -0,0 +1,115 @@
+"""
+dotmd-parser — Dependency graph parser for .md skill files.
+
+Parse @include/@delegate/@ref directives, build dependency graphs, resolve
+templates, and produce a token-efficient on-disk index for AI agents.
+
+API:
+    from dotmd_parser import build_graph, resolve, dependents_of, summary
+    from dotmd_parser import build_index, save_index, load_index
+    from dotmd_parser import digest, tree, affects
+"""
+
+__version__ = "0.5.0"
+
+from dotmd_parser.parser import (
+    build_graph,
+    resolve,
+    dependents_of,
+    parse_directives,
+    parse_read_refs,
+    parse_placeholders,
+    parse_description,
+    parse_deps_yml,
+    hash_content,
+    summary,
+)
+from dotmd_parser.index import (
+    build_index,
+    build_scoped_index,
+    compact_graph,
+    merge_index,
+    save_index,
+    load_index,
+    needs_rebuild,
+    changed_files,
+    default_index_path,
+)
+from dotmd_parser.digest import (
+    digest,
+    tree,
+    affects,
+    deps_of,
+)
+from dotmd_parser.analyze import (
+    analyze_dependencies,
+    apply_analysis,
+    apply_analysis_from_file,
+    estimate_cost,
+    format_cost_estimate,
+    format_host_agent_plan,
+    generate_directives,
+    format_proposal,
+    scan_documents,
+    save_deps_yml,
+    load_deps_yml,
+    MODEL_PRICING,
+)
+from dotmd_parser.inventory import (
+    inventory,
+    format_inventory,
+    suggest_next_command,
+    TEXT_EXTENSIONS,
+    BINARY_EXTENSIONS,
+    MARKDOWN_EXTENSIONS,
+)
+
+__all__ = [
+    "__version__",
+    # parser
+    "build_graph",
+    "resolve",
+    "dependents_of",
+    "parse_directives",
+    "parse_read_refs",
+    "parse_placeholders",
+    "parse_description",
+    "parse_deps_yml",
+    "hash_content",
+    "summary",
+    # index
+    "build_index",
+    "build_scoped_index",
+    "compact_graph",
+    "merge_index",
+    "save_index",
+    "load_index",
+    "needs_rebuild",
+    "changed_files",
+    "default_index_path",
+    # digest
+    "digest",
+    "tree",
+    "affects",
+    "deps_of",
+    # analyze
+    "analyze_dependencies",
+    "apply_analysis",
+    "apply_analysis_from_file",
+    "estimate_cost",
+    "format_cost_estimate",
+    "format_host_agent_plan",
+    "generate_directives",
+    "format_proposal",
+    "scan_documents",
+    "save_deps_yml",
+    "load_deps_yml",
+    "MODEL_PRICING",
+    # inventory
+    "inventory",
+    "format_inventory",
+    "suggest_next_command",
+    "TEXT_EXTENSIONS",
+    "BINARY_EXTENSIONS",
+    "MARKDOWN_EXTENSIONS",
+]