embedm 0.9.0__tar.gz

embedm-0.9.0/LICENSE.txt

@@ -0,0 +1,9 @@
+
+
+Copyright 2026 Fultslop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

embedm-0.9.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: embedm
+Version: 0.9.0
+Summary: A Python tool for embedding files, code snippets, and generating tables of contents in Markdown documents with built-in safety limits and validation
+Author: Fultslop
+License: MIT
+Project-URL: Homepage, https://github.com/Fultslop/embedm
+Project-URL: Repository, https://github.com/Fultslop/embedm
+Project-URL: Issues, https://github.com/Fultslop/embedm/issues
+Keywords: markdown,embedding,documentation,code-snippets,table-of-contents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# EmbedM
+
+version 0.9.0
+
+A Markdown compiler driven by source files.
+
+  - [How It Works](#how-it-works)
+  - [Use Cases](#use-cases)
+    - [Keeping code documentation in sync](#keeping-code-documentation-in-sync)
+    - [Live metadata in a README or changelog](#live-metadata-in-a-readme-or-changelog)
+    - [Data tables without copy-paste](#data-tables-without-copy-paste)
+    - [CI drift detection](#ci-drift-detection)
+    - [AI agent context documents](#ai-agent-context-documents)
+  - [Directives](#directives)
+  - [Quick Start](#quick-start)
+  - [Features](#features)
+  - [Documentation](#documentation)
+  - [Project Background](#project-background)
+  - [License](#license)
+  - [Contributing](#contributing)
+
+## How It Works
+
+EmbedM compiles Markdown documents from directive blocks. Each directive references a source — a code file, a data query, a CSV table, or another document — and is replaced with the extracted, formatted content on compile. Change the source; recompile; the document is current.
+
+## Use Cases
+
+### Keeping code documentation in sync
+
+Embed a function directly from the source file, scoped by a named region or by symbol name. When the implementation changes the docs regenerate on the next compile — no copy-paste, no drift.
+
+````yaml
+type: file
+source: src/api/handlers.java
+symbol: UserHandler.createUser
+title: "POST /users"
+link: true
+````
+
+### Live metadata in a README or changelog
+
+Pull version numbers, project names, and other values from `pyproject.toml`, `package.json`, or any JSON/YAML/TOML/XML file. The version at the top of this page is a live example — it is compiled from `pyproject.toml` at build time.
+
+````yaml
+type: query-path
+source: pyproject.toml
+path: project.version
+format: "Released: **v{value}**"
+````
+
+### Data tables without copy-paste
+
+Embed CSV or TSV data as formatted Markdown tables. Apply column selection, filtering, and sorting inline — the source file is the single source of truth.
+
+````yaml
+type: table
+source: reports/q4-summary.csv
+select: "Region as Region, Revenue as Revenue_USD"
+order_by: "Revenue_USD desc"
+limit: 10
+````
+
+### CI drift detection
+
+Use `--verify` in your pipeline to catch documentation that has fallen behind its sources. Exit code 1 if any compiled file is stale.
+
+```
+embedm ./docs/src --verify -d ./docs/compiled
+```
+
+### AI agent context documents
+
+Use `recall` to query a large document — a devlog, a decision log, an ADR set — and extract the sentences most relevant to a given topic. Compose multiple queries into a single compiled context file that an AI assistant reads at session start.
+
+````yaml
+type: recall
+source: ./devlog.md
+query: "validation transform boundary error handling"
+max_sentences: 5
+````
+
+EmbedM itself uses this: its agent context file is compiled from the project devlog using four targeted recall queries — plugin conventions, architectural rules, common mistakes, and the active spec. The context window stays focused without manual curation.
+
+## Directives
+
+Directives are fenced YAML blocks tagged `` ```yaml embedm ``. On compile, each is replaced in-place with the extracted content:
+
+````yaml
+type: file
+source: src/config/defaults.py
+region: connection_defaults
+````
+
+```python
+# connection_defaults
+HOST = "localhost"
+PORT = 5432
+TIMEOUT = 30
+POOL_SIZE = 10
+```
+
+Structured data queries render inline:
+
+````yaml
+type: query-path
+source: config/app.yaml
+path: database.pool_size
+format: "Default pool size: **{value}**"
+````
+
+> Default pool size: **10**
+
+## Quick Start
+
+**Install**
+
+```
+(coming soon) pip install embedm
+```
+
+Or from source:
+
+```
+git clone https://github.com/Fultslop/embedm.git
+cd embedm
+pip install -e .
+```
+
+**Compile a single file**
+
+```
+embedm content.md -o compiled/content.md
+```
+
+**Compile a directory**
+
+```
+embedm ./docs/src -d ./docs/compiled
+```
+
+**Preview without writing**
+
+```
+embedm content.md -n
+```
+
+**Check that compiled files are up to date**
+
+```
+embedm ./docs/src --verify -d ./docs/compiled
+```
+
+**Generate a default config file**
+
+```
+embedm --init
+```
+
+## Features
+
+**File embedding**
+- Embed entire files, line ranges (`5..10`), or named regions (`md.start:name` / `md.end:name`)
+- Markdown sources are merged inline; all other types are wrapped in a fenced code block
+- Optional title, source link, and line-number annotation
+
+**Symbol extraction**
+- Extract classes and methods by name from C/C++, C#, and Java source files
+- Dot-notation for nested symbols: `OuterClass.InnerClass.methodName`
+- Overload disambiguation: `add(int, int)` vs `add(int, int, int)`
+
+**Structured data**
+- Query any value from JSON, YAML, TOML, or XML using dot-notation paths
+- Scalars render inline; dicts and lists render as YAML code blocks
+- Format strings for inline interpolation: `"version {value}"`
+
+**Data tables**
+- Render CSV and TSV files as Markdown tables
+- Column selection, row filtering (exact match and comparison operators), sorting, pagination
+
+**Table of contents**
+- Auto-generated from document headings, including headings in embedded files
+- GitHub-compatible anchor links
+
+**AI context**
+- `synopsis` — generate a condensed summary of a document
+- `recall` — build structured retrieval blocks for AI agent context files
+
+**Recursive embedding**
+- Markdown files that embed other Markdown files, up to a configurable depth
+
+**Safety**
+- Configurable limits on file size, memory, recursion depth, and embed output size
+- `--verify` mode for CI drift detection
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [CLI Reference](doc/manual/compiled/cli.md) | All flags, input modes, and exit codes |
+| [Configuration Reference](doc/manual/compiled/configuration.md) | `embedm-config.yaml` properties and defaults |
+| [File Plugin](doc/manual/compiled/file_plugin.md) | File embedding, regions, lines, symbol extraction |
+| [Query-Path Plugin](doc/manual/compiled/query_path_plugin.md) | Structured data extraction from JSON/YAML/TOML/XML |
+| [Table Plugin](doc/manual/compiled/table_plugin.md) | CSV/TSV tables with filtering and sorting |
+| [Toc Plugin](doc/manual/compiled/toc_plugin.md) | Table-of-contents generation |
+| [Architecture](doc/manual/compiled/architecture.md) | System design, plugin model, plan/compile pipeline |
+
+## Project Background
+
+EmbedM is part of an exploration into how far AI-assisted development can go when building a non-trivial tool that could be used in a production CD/CI chain. This project has been built based on a _human_ defined architecture, functional spec and a series of interface contracts, then implemented using using [Claude](https://claude.ai/) and to a lesser extent [Google Gemini](https://gemini.google.com/app). 
+
+## License
+
+MIT License — see LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.

embedm-0.9.0/README.md

@@ -0,0 +1,217 @@
+# EmbedM
+
+version 0.9.0
+
+A Markdown compiler driven by source files.
+
+  - [How It Works](#how-it-works)
+  - [Use Cases](#use-cases)
+    - [Keeping code documentation in sync](#keeping-code-documentation-in-sync)
+    - [Live metadata in a README or changelog](#live-metadata-in-a-readme-or-changelog)
+    - [Data tables without copy-paste](#data-tables-without-copy-paste)
+    - [CI drift detection](#ci-drift-detection)
+    - [AI agent context documents](#ai-agent-context-documents)
+  - [Directives](#directives)
+  - [Quick Start](#quick-start)
+  - [Features](#features)
+  - [Documentation](#documentation)
+  - [Project Background](#project-background)
+  - [License](#license)
+  - [Contributing](#contributing)
+
+## How It Works
+
+EmbedM compiles Markdown documents from directive blocks. Each directive references a source — a code file, a data query, a CSV table, or another document — and is replaced with the extracted, formatted content on compile. Change the source; recompile; the document is current.
+
+## Use Cases
+
+### Keeping code documentation in sync
+
+Embed a function directly from the source file, scoped by a named region or by symbol name. When the implementation changes the docs regenerate on the next compile — no copy-paste, no drift.
+
+````yaml
+type: file
+source: src/api/handlers.java
+symbol: UserHandler.createUser
+title: "POST /users"
+link: true
+````
+
+### Live metadata in a README or changelog
+
+Pull version numbers, project names, and other values from `pyproject.toml`, `package.json`, or any JSON/YAML/TOML/XML file. The version at the top of this page is a live example — it is compiled from `pyproject.toml` at build time.
+
+````yaml
+type: query-path
+source: pyproject.toml
+path: project.version
+format: "Released: **v{value}**"
+````
+
+### Data tables without copy-paste
+
+Embed CSV or TSV data as formatted Markdown tables. Apply column selection, filtering, and sorting inline — the source file is the single source of truth.
+
+````yaml
+type: table
+source: reports/q4-summary.csv
+select: "Region as Region, Revenue as Revenue_USD"
+order_by: "Revenue_USD desc"
+limit: 10
+````
+
+### CI drift detection
+
+Use `--verify` in your pipeline to catch documentation that has fallen behind its sources. Exit code 1 if any compiled file is stale.
+
+```
+embedm ./docs/src --verify -d ./docs/compiled
+```
+
+### AI agent context documents
+
+Use `recall` to query a large document — a devlog, a decision log, an ADR set — and extract the sentences most relevant to a given topic. Compose multiple queries into a single compiled context file that an AI assistant reads at session start.
+
+````yaml
+type: recall
+source: ./devlog.md
+query: "validation transform boundary error handling"
+max_sentences: 5
+````
+
+EmbedM itself uses this: its agent context file is compiled from the project devlog using four targeted recall queries — plugin conventions, architectural rules, common mistakes, and the active spec. The context window stays focused without manual curation.
+
+## Directives
+
+Directives are fenced YAML blocks tagged `` ```yaml embedm ``. On compile, each is replaced in-place with the extracted content:
+
+````yaml
+type: file
+source: src/config/defaults.py
+region: connection_defaults
+````
+
+```python
+# connection_defaults
+HOST = "localhost"
+PORT = 5432
+TIMEOUT = 30
+POOL_SIZE = 10
+```
+
+Structured data queries render inline:
+
+````yaml
+type: query-path
+source: config/app.yaml
+path: database.pool_size
+format: "Default pool size: **{value}**"
+````
+
+> Default pool size: **10**
+
+## Quick Start
+
+**Install**
+
+```
+(coming soon) pip install embedm
+```
+
+Or from source:
+
+```
+git clone https://github.com/Fultslop/embedm.git
+cd embedm
+pip install -e .
+```
+
+**Compile a single file**
+
+```
+embedm content.md -o compiled/content.md
+```
+
+**Compile a directory**
+
+```
+embedm ./docs/src -d ./docs/compiled
+```
+
+**Preview without writing**
+
+```
+embedm content.md -n
+```
+
+**Check that compiled files are up to date**
+
+```
+embedm ./docs/src --verify -d ./docs/compiled
+```
+
+**Generate a default config file**
+
+```
+embedm --init
+```
+
+## Features
+
+**File embedding**
+- Embed entire files, line ranges (`5..10`), or named regions (`md.start:name` / `md.end:name`)
+- Markdown sources are merged inline; all other types are wrapped in a fenced code block
+- Optional title, source link, and line-number annotation
+
+**Symbol extraction**
+- Extract classes and methods by name from C/C++, C#, and Java source files
+- Dot-notation for nested symbols: `OuterClass.InnerClass.methodName`
+- Overload disambiguation: `add(int, int)` vs `add(int, int, int)`
+
+**Structured data**
+- Query any value from JSON, YAML, TOML, or XML using dot-notation paths
+- Scalars render inline; dicts and lists render as YAML code blocks
+- Format strings for inline interpolation: `"version {value}"`
+
+**Data tables**
+- Render CSV and TSV files as Markdown tables
+- Column selection, row filtering (exact match and comparison operators), sorting, pagination
+
+**Table of contents**
+- Auto-generated from document headings, including headings in embedded files
+- GitHub-compatible anchor links
+
+**AI context**
+- `synopsis` — generate a condensed summary of a document
+- `recall` — build structured retrieval blocks for AI agent context files
+
+**Recursive embedding**
+- Markdown files that embed other Markdown files, up to a configurable depth
+
+**Safety**
+- Configurable limits on file size, memory, recursion depth, and embed output size
+- `--verify` mode for CI drift detection
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [CLI Reference](doc/manual/compiled/cli.md) | All flags, input modes, and exit codes |
+| [Configuration Reference](doc/manual/compiled/configuration.md) | `embedm-config.yaml` properties and defaults |
+| [File Plugin](doc/manual/compiled/file_plugin.md) | File embedding, regions, lines, symbol extraction |
+| [Query-Path Plugin](doc/manual/compiled/query_path_plugin.md) | Structured data extraction from JSON/YAML/TOML/XML |
+| [Table Plugin](doc/manual/compiled/table_plugin.md) | CSV/TSV tables with filtering and sorting |
+| [Toc Plugin](doc/manual/compiled/toc_plugin.md) | Table-of-contents generation |
+| [Architecture](doc/manual/compiled/architecture.md) | System design, plugin model, plan/compile pipeline |
+
+## Project Background
+
+EmbedM is part of an exploration into how far AI-assisted development can go when building a non-trivial tool that could be used in a production CD/CI chain. This project has been built based on a _human_ defined architecture, functional spec and a series of interface contracts, then implemented using using [Claude](https://claude.ai/) and to a lesser extent [Google Gemini](https://gemini.google.com/app). 
+
+## License
+
+MIT License — see LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.

embedm-0.9.0/pyproject.toml

@@ -0,0 +1,195 @@
+[project]
+name = "embedm"
+version = "0.9.0"
+description = "A Python tool for embedding files, code snippets, and generating tables of contents in Markdown documents with built-in safety limits and validation"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Fultslop"}
+]
+keywords = ["markdown", "embedding", "documentation", "code-snippets", "table-of-contents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Documentation",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Text Processing :: Markup :: Markdown",
+]
+
+dependencies = [
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Fultslop/embedm"
+Repository = "https://github.com/Fultslop/embedm"
+Issues = "https://github.com/Fultslop/embedm/issues"
+
+[project.scripts]
+embedm = "embedm.application.orchestration:main"
+
+# md.start:entry_points
+[project.entry-points."embedm.plugins"]
+embedm_file = "embedm_plugins.file_plugin:FilePlugin"
+table_of_contents = "embedm_plugins.toc_plugin:ToCPlugin"
+hello_world = "embedm_plugins.hello_world_plugin:HelloWorldPlugin"
+table = "embedm_plugins.table_plugin:TablePlugin"
+synopsis = "embedm_plugins.synopsis_plugin:SynopsisPlugin"
+recall = "embedm_plugins.recall_plugin:RecallPlugin"
+query_path = "embedm_plugins.query_path_plugin:QueryPathPlugin"
+# md.end:entry_points
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+norecursedirs = ["archive", ".*", "dist", "build"]
+python_files = ["test_*.py", "*_test.py"]
+python_functions = ["test_*", "*_test"]
+
+addopts = [
+    "--verbose",
+    "--color=yes",
+    "--cov=embedm",
+    "--cov=embedm_plugins",
+    "--cov-report=term-missing:skip-covered",
+    "--cov-report=html",
+    "--cov-report=json",
+]
+
+[tool.coverage.run]
+source = ["embedm"]
+omit = [
+    "*/tests/*", 
+    "*/test_*.py", 
+    "src/embedm/__main__.py", 
+    "src/embedm/application/console.py",
+    "src/embedm/application/orchestration.py"
+ ]
+
+[tool.coverage.report]
+fail_under = 70
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+
+
+# -------------------
+# IMPORT LINTER
+# -------------------
+[tool.importlinter]
+root_packages = ["embedm", "embedm_plugins"]
+include_external_packages = false
+
+[[tool.importlinter.contracts]]
+name = "Domain must not import from infrastructure, cli, or application"
+type = "forbidden"
+source_modules = ["embedm.domain"]
+forbidden_modules = ["embedm.infrastructure", "embedm.application"]
+
+[[tool.importlinter.contracts]]
+name = "Parsing must not import from infrastructure or application"
+type = "forbidden"
+source_modules = ["embedm.parsing"]
+forbidden_modules = ["embedm.infrastructure", "embedm.application"]
+
+[[tool.importlinter.contracts]]
+name = "Plugins must not import from application"
+type = "forbidden"
+source_modules = ["embedm.plugins"]
+forbidden_modules = ["embedm.application"]
+
+[[tool.importlinter.contracts]]
+name = "Infrastructure must not import from application, parsing, or plugins"
+type = "forbidden"
+source_modules = ["embedm.infrastructure"]
+forbidden_modules = ["embedm.application", "embedm.parsing", "embedm.plugins"]
+
+[[tool.importlinter.contracts]]
+name = "Embedm plugins must not import from application"
+type = "forbidden"
+source_modules = ["embedm_plugins"]
+forbidden_modules = ["embedm.application" ]
+
+# -------------------
+# VULTURE
+# -------------------
+[tool.vulture]
+paths = ["src/"]
+min_confidence = 80
+exclude = ["__pycache__"]
+
+# -------------------
+# RADON / XENON
+# -------------------
+# Xenon thresholds (run via CLI):
+#   xenon src/ --max-absolute B --max-modules A --max-average A
+
+# -------------------
+# RUFF
+# -------------------
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle
+    "F",   # pyflakes
+    "W",
+    "I",   # import sorting
+    "B",   # bugbear
+    "C4",  # comprehensions
+    "UP",  # pyupgrade
+    "ARG", # unused args
+    "SIM", # simplifications
+]
+ignore = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+# -------------------
+# MYPY
+# -------------------
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_configs = true
+warn_return_any = true
+warn_unreachable = true
+no_implicit_optional = true
+disallow_untyped_defs = true
+disallow_any_generics = true
+check_untyped_defs = true
+exclude = ["tests/"]

embedm-0.9.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

embedm-0.9.0/src/embedm/__main__.py

@@ -0,0 +1,3 @@
+from embedm.application.orchestration import main
+
+main()