markstay 0.1.0__tar.gz

markstay-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+.venv/

markstay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 markstaymd
+
+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.

markstay-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: markstay
+Version: 0.1.0
+Summary: Python reference implementation of the markstay spec (v1.1): source-level block identity for Markdown
+Project-URL: Homepage, https://markstay.org
+Project-URL: Repository, https://github.com/markstaymd/markstay-py
+Project-URL: Issues, https://github.com/markstaymd/markstay-py/issues
+Author-email: markstaymd <markstaymd@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: block-identity,content-addressed,diff,linter,markdown,markstay,spec
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.9
+Provides-Extra: commonmark
+Requires-Dist: markdown-it-py>=2; extra == 'commonmark'
+Description-Content-Type: text/markdown
+
+# markstay , Python reference implementation (v1 core)
+
+The Python reference implementation of the [markstay spec](https://markstay.org)
+(v1.1). markstay is a source-level identity primitive for Markdown blocks: an id
+token that **stays** bound to its block across edits (marker `stay:`), so a
+reference to a block survives the document being rewritten, including by an LLM.
+
+This is the **parser-free core**: everything string-level and parser-independent
+(§8 hashing, §3/§4 marker grammar, §5 blank-line segmentation, §7/§11 lint, §9
+quote recovery, §9.1 resolution ladder). It mirrors the JavaScript reference
+([`markstay` on npm](https://www.npmjs.com/package/markstay)); both are gated by a
+shared language-neutral conformance corpus, which turns "two implementations
+agree" from an assertion into a tested fact.
+
+## Install
+
+```sh
+pip install markstay
+```
+
+Zero runtime dependencies (Python standard library only). CommonMark-tree
+segmentation (§5.2) is an optional extra:
+
+```sh
+pip install "markstay[commonmark]"   # pulls in markdown-it-py
+```
+
+Requires Python >= 3.9.
+
+## Library
+
+```python
+import markstay as M
+
+md = "The ingest stage retries three times.\n<!-- stay:a1b2 -->\n"
+
+# parse into content blocks with attached markers (§5)
+blocks = M.parse_document(md)
+
+# well-formedness + intra-doc invariants (§7): duplicate/orphan/malformed/drift
+_, findings = M.lint_document(md)
+
+# regeneration diff (§11): what an edit did to the ids (dropped/duplicated/moved)
+findings = M.lint_diff(before_md, after_md)
+
+# §8 content hash (ASCII-normalized SHA-256)
+M.body_hash("some block body")
+
+# §9.1 resolution ladder: re-attach ids after an edit, or report DETACHED
+anchors = M.build_anchors(before_md)
+resolutions = M.resolve(anchors, after_md)   # id -> marker | hash | quote | detached
+```
+
+Public API (mirrors the JS `index.js` surface): `normalize_body`, `body_hash`,
+`Marker`, `find_markers`, `strip_markers`, `segment_blank_line`,
+`segment_commonmark`, `Block`, `parse_document`, `Finding`, `lint_document`,
+`lint_diff`, `sort_findings`, `has_errors`, `Selector`, `normalize`,
+`body_score`, `context_bonus`, `best_match`, `CONTEXT_CHARS`, `Anchor`,
+`Resolution`, `build_anchors`, `resolve`, `DEFAULT_THRESHOLD`, `DEFAULT_MARGIN`.
+
+## CLI
+
+```sh
+markstay FILE [FILE ...]            # well-formedness + intra-doc checks
+markstay --before OLD.md NEW.md     # regeneration diff (dropped/duplicated/relocated ids)
+markstay --json ...                 # machine-readable findings
+markstay --commonmark ...           # §5.2 CommonMark-tree segmentation (needs the extra)
+```
+
+Exit status is non-zero when any error-level finding is reported, so it can gate
+a commit hook or an agent's post-edit step.
+
+## The conformance corpus (the actual deliverable)
+
+The corpus under [`conformance/`](conformance) is shared with the JavaScript
+reference. **276 vectors** across two tiers:
+
+- **`spec/`** , hand-authored from the spec prose, asserting what the *words*
+  require. These are authority; a `spec/` vector the reference fails is a
+  reference bug, not a corpus error.
+- **`gen/`** , emitted from the reference for breadth/regression.
+
+The JS reference runs the same JSON, so the two runners are a cross-impl
+regression sentinel: any later change to either implementation that breaks
+agreement fails one of them.
+
+## Running the tests
+
+```sh
+pip install -e ".[commonmark]"
+pytest
+```
+
+## License
+
+MIT

markstay-0.1.0/README.md

@@ -0,0 +1,96 @@
+# markstay , Python reference implementation (v1 core)
+
+The Python reference implementation of the [markstay spec](https://markstay.org)
+(v1.1). markstay is a source-level identity primitive for Markdown blocks: an id
+token that **stays** bound to its block across edits (marker `stay:`), so a
+reference to a block survives the document being rewritten, including by an LLM.
+
+This is the **parser-free core**: everything string-level and parser-independent
+(§8 hashing, §3/§4 marker grammar, §5 blank-line segmentation, §7/§11 lint, §9
+quote recovery, §9.1 resolution ladder). It mirrors the JavaScript reference
+([`markstay` on npm](https://www.npmjs.com/package/markstay)); both are gated by a
+shared language-neutral conformance corpus, which turns "two implementations
+agree" from an assertion into a tested fact.
+
+## Install
+
+```sh
+pip install markstay
+```
+
+Zero runtime dependencies (Python standard library only). CommonMark-tree
+segmentation (§5.2) is an optional extra:
+
+```sh
+pip install "markstay[commonmark]"   # pulls in markdown-it-py
+```
+
+Requires Python >= 3.9.
+
+## Library
+
+```python
+import markstay as M
+
+md = "The ingest stage retries three times.\n<!-- stay:a1b2 -->\n"
+
+# parse into content blocks with attached markers (§5)
+blocks = M.parse_document(md)
+
+# well-formedness + intra-doc invariants (§7): duplicate/orphan/malformed/drift
+_, findings = M.lint_document(md)
+
+# regeneration diff (§11): what an edit did to the ids (dropped/duplicated/moved)
+findings = M.lint_diff(before_md, after_md)
+
+# §8 content hash (ASCII-normalized SHA-256)
+M.body_hash("some block body")
+
+# §9.1 resolution ladder: re-attach ids after an edit, or report DETACHED
+anchors = M.build_anchors(before_md)
+resolutions = M.resolve(anchors, after_md)   # id -> marker | hash | quote | detached
+```
+
+Public API (mirrors the JS `index.js` surface): `normalize_body`, `body_hash`,
+`Marker`, `find_markers`, `strip_markers`, `segment_blank_line`,
+`segment_commonmark`, `Block`, `parse_document`, `Finding`, `lint_document`,
+`lint_diff`, `sort_findings`, `has_errors`, `Selector`, `normalize`,
+`body_score`, `context_bonus`, `best_match`, `CONTEXT_CHARS`, `Anchor`,
+`Resolution`, `build_anchors`, `resolve`, `DEFAULT_THRESHOLD`, `DEFAULT_MARGIN`.
+
+## CLI
+
+```sh
+markstay FILE [FILE ...]            # well-formedness + intra-doc checks
+markstay --before OLD.md NEW.md     # regeneration diff (dropped/duplicated/relocated ids)
+markstay --json ...                 # machine-readable findings
+markstay --commonmark ...           # §5.2 CommonMark-tree segmentation (needs the extra)
+```
+
+Exit status is non-zero when any error-level finding is reported, so it can gate
+a commit hook or an agent's post-edit step.
+
+## The conformance corpus (the actual deliverable)
+
+The corpus under [`conformance/`](conformance) is shared with the JavaScript
+reference. **276 vectors** across two tiers:
+
+- **`spec/`** , hand-authored from the spec prose, asserting what the *words*
+  require. These are authority; a `spec/` vector the reference fails is a
+  reference bug, not a corpus error.
+- **`gen/`** , emitted from the reference for breadth/regression.
+
+The JS reference runs the same JSON, so the two runners are a cross-impl
+regression sentinel: any later change to either implementation that breaks
+agreement fails one of them.
+
+## Running the tests
+
+```sh
+pip install -e ".[commonmark]"
+pytest
+```
+
+## License
+
+MIT

markstay-0.1.0/conformance/gen/diff.json

@@ -0,0 +1,77 @@
+{
+  "category": "diff",
+  "tier": "gen",
+  "vectors": [
+    {
+      "before": "A.\n<!-- stay:a -->\n\nB.\n<!-- stay:b -->\n",
+      "after": "A.\n<!-- stay:a -->\n\nB rewritten without its marker.\n",
+      "findings": [
+        {
+          "level": "error",
+          "code": "DROPPED_ID",
+          "id": "b"
+        }
+      ],
+      "name": "diff-000"
+    },
+    {
+      "before": "A.\n<!-- stay:a -->\n",
+      "after": "A.\n<!-- stay:a -->\n\nCopy of A.\n<!-- stay:a -->\n",
+      "findings": [
+        {
+          "level": "error",
+          "code": "DUPLICATED_ID",
+          "id": "a"
+        }
+      ],
+      "name": "diff-001"
+    },
+    {
+      "before": "A.\n<!-- stay:a -->\n",
+      "after": "A.\n<!-- stay:a -->\n\nBrand new block.\n<!-- stay:c -->\n",
+      "findings": [
+        {
+          "level": "info",
+          "code": "NEW_ID",
+          "id": "c"
+        }
+      ],
+      "name": "diff-002"
+    },
+    {
+      "before": "Alpha content.\n<!-- stay:aaa -->\n\nBeta content.\n<!-- stay:bbb -->\n",
+      "after": "Beta content.\n<!-- stay:aaa -->\n\nAlpha content.\n<!-- stay:bbb -->\n",
+      "findings": [
+        {
+          "level": "error",
+          "code": "RELOCATED_ID",
+          "id": "aaa"
+        },
+        {
+          "level": "error",
+          "code": "RELOCATED_ID",
+          "id": "bbb"
+        }
+      ],
+      "name": "diff-003"
+    },
+    {
+      "before": "Alpha content.\n<!-- stay:aaa -->\n",
+      "after": "Alpha content, now revised.\n<!-- stay:aaa -->\n",
+      "findings": [
+        {
+          "level": "warn",
+          "code": "HASH_DRIFT",
+          "id": "aaa"
+        }
+      ],
+      "name": "diff-004"
+    },
+    {
+      "before": "Keep me.\n<!-- stay:k -->\n",
+      "after": "Keep me.\n<!-- stay:k -->\n",
+      "findings": [],
+      "name": "diff-005"
+    }
+  ]
+}

markstay-0.1.0/conformance/gen/hash.json

@@ -0,0 +1,174 @@
+{
+  "category": "hash",
+  "tier": "gen",
+  "vectors": [
+    {
+      "body": "A single normalized paragraph.",
+      "normalized": "A single normalized paragraph.",
+      "sha256": "23d8cab5b86a660888effcf0c4371a2aadb5a30beb1be8b4e14c8bfc51739154",
+      "truncations": {
+        "4": "23d8",
+        "8": "23d8cab5",
+        "12": "23d8cab5b86a",
+        "16": "23d8cab5b86a6608"
+      },
+      "name": "hash-000"
+    },
+    {
+      "body": "trailing spaces here   \nand a tab\there\t",
+      "normalized": "trailing spaces here\nand a tab\there",
+      "sha256": "7b5e1ac324fa21ecc3523b342bb2c4d16a8a54a16d58d904f9dfd12243f6c5d3",
+      "truncations": {
+        "4": "7b5e",
+        "8": "7b5e1ac3",
+        "12": "7b5e1ac324fa",
+        "16": "7b5e1ac324fa21ec"
+      },
+      "name": "hash-001"
+    },
+    {
+      "body": "windows\r\nline\r\nendings",
+      "normalized": "windows\nline\nendings",
+      "sha256": "0ce3289bdb1ff9c4923c4edb0d37e54292ce18e647611419a9117909fb602249",
+      "truncations": {
+        "4": "0ce3",
+        "8": "0ce3289b",
+        "12": "0ce3289bdb1f",
+        "16": "0ce3289bdb1ff9c4"
+      },
+      "name": "hash-002"
+    },
+    {
+      "body": "lone\rcarriage\rreturns",
+      "normalized": "lone\ncarriage\nreturns",
+      "sha256": "33c5d7f8e9e24720f276c251b18d28c80b1bf6c8d60deb39b01167bf5685e7c2",
+      "truncations": {
+        "4": "33c5",
+        "8": "33c5d7f8",
+        "12": "33c5d7f8e9e2",
+        "16": "33c5d7f8e9e24720"
+      },
+      "name": "hash-003"
+    },
+    {
+      "body": "\n\n\nleading and trailing blank lines\n\n\n",
+      "normalized": "leading and trailing blank lines",
+      "sha256": "88354b446814a0b4c0e33cb99cd60418104bc44438f62ff6096000189ce3450f",
+      "truncations": {
+        "4": "8835",
+        "8": "88354b44",
+        "12": "88354b446814",
+        "16": "88354b446814a0b4"
+      },
+      "name": "hash-004"
+    },
+    {
+      "body": "   \n  leading blank-ish lines with whitespace\nbody line\n   \n",
+      "normalized": "  leading blank-ish lines with whitespace\nbody line",
+      "sha256": "85c6052d5f101575261ccf0cdeb93436e5929104f3107408261915971d5bb83b",
+      "truncations": {
+        "4": "85c6",
+        "8": "85c6052d",
+        "12": "85c6052d5f10",
+        "16": "85c6052d5f101575"
+      },
+      "name": "hash-005"
+    },
+    {
+      "body": "```\ncode with trailing ws   \n\tindented\t\n```",
+      "normalized": "```\ncode with trailing ws\n\tindented\n```",
+      "sha256": "08af614812a08ac12d45b113e923f040667a69bdba12a22ba169b9db69a40072",
+      "truncations": {
+        "4": "08af",
+        "8": "08af6148",
+        "12": "08af614812a0",
+        "16": "08af614812a08ac1"
+      },
+      "name": "hash-006"
+    },
+    {
+      "body": "café au lait , non-ASCII UTF-8 body",
+      "normalized": "café au lait , non-ASCII UTF-8 body",
+      "sha256": "60627234380043936d04070735bd0b17793e13373af36c734a6fae6a5d5fd850",
+      "truncations": {
+        "4": "6062",
+        "8": "60627234",
+        "12": "606272343800",
+        "16": "6062723438004393"
+      },
+      "name": "hash-007"
+    },
+    {
+      "body": "emoji body 😀 stays stable",
+      "normalized": "emoji body 😀 stays stable",
+      "sha256": "11f515982f0d3bde2de3245f973436fdb2f7d051c244857bc567866cbea8ccab",
+      "truncations": {
+        "4": "11f5",
+        "8": "11f51598",
+        "12": "11f515982f0d",
+        "16": "11f515982f0d3bde"
+      },
+      "name": "hash-008"
+    },
+    {
+      "body": "line one\nline two\nline three",
+      "normalized": "line one\nline two\nline three",
+      "sha256": "26a5cd654e540e91433a2f237e2709743fc4753e764deb74ed37299c2f338ece",
+      "truncations": {
+        "4": "26a5",
+        "8": "26a5cd65",
+        "12": "26a5cd654e54",
+        "16": "26a5cd654e540e91"
+      },
+      "name": "hash-009"
+    },
+    {
+      "body": "",
+      "normalized": "",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+      "truncations": {
+        "4": "e3b0",
+        "8": "e3b0c442",
+        "12": "e3b0c44298fc",
+        "16": "e3b0c44298fc1c14"
+      },
+      "name": "hash-010"
+    },
+    {
+      "body": "   ",
+      "normalized": "",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+      "truncations": {
+        "4": "e3b0",
+        "8": "e3b0c442",
+        "12": "e3b0c44298fc",
+        "16": "e3b0c44298fc1c14"
+      },
+      "name": "hash-011"
+    },
+    {
+      "body": "\n\n",
+      "normalized": "",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+      "truncations": {
+        "4": "e3b0",
+        "8": "e3b0c442",
+        "12": "e3b0c44298fc",
+        "16": "e3b0c44298fc1c14"
+      },
+      "name": "hash-012"
+    },
+    {
+      "body": "one",
+      "normalized": "one",
+      "sha256": "7692c3ad3540bb803c020b3aee66cd8887123234ea0c6e7143c0add73ff431ed",
+      "truncations": {
+        "4": "7692",
+        "8": "7692c3ad",
+        "12": "7692c3ad3540",
+        "16": "7692c3ad3540bb80"
+      },
+      "name": "hash-013"
+    }
+  ]
+}

markstay-0.1.0/conformance/gen/lint.json

@@ -0,0 +1,81 @@
+{
+  "category": "lint",
+  "tier": "gen",
+  "vectors": [
+    {
+      "doc": "The order pipeline ingests messages and normalizes them.\n<!-- stay:8f24 hash=sha256:9c26 -->\n",
+      "findings": [],
+      "name": "lint-000"
+    },
+    {
+      "doc": "Users authenticate with an API key.\n<!-- stay:8f24 hash=sha256:9690 -->\n",
+      "findings": [],
+      "name": "lint-001"
+    },
+    {
+      "doc": "Block one.\n<!-- stay:dup -->\n\nBlock two.\n<!-- stay:dup -->\n",
+      "findings": [
+        {
+          "level": "error",
+          "code": "DUPLICATE_ID",
+          "id": "dup",
+          "line": 5
+        }
+      ],
+      "name": "lint-002"
+    },
+    {
+      "doc": "A paragraph.\n<!-- stay:note=hello -->\n",
+      "findings": [
+        {
+          "level": "error",
+          "code": "MALFORMED_MARKER",
+          "id": null,
+          "line": 2
+        }
+      ],
+      "name": "lint-003"
+    },
+    {
+      "doc": "<!-- stay:loose -->\n\nReal content below.\n",
+      "findings": [
+        {
+          "level": "error",
+          "code": "ORPHAN_MARKER",
+          "id": "loose",
+          "line": 1
+        }
+      ],
+      "name": "lint-004"
+    },
+    {
+      "doc": "Edited content.\n<!-- stay:z9 hash=sha256:dead -->\n",
+      "findings": [
+        {
+          "level": "warn",
+          "code": "HASH_DRIFT",
+          "id": "z9",
+          "line": 2
+        }
+      ],
+      "name": "lint-005"
+    },
+    {
+      "doc": "An MDX block.\n{/* stay:mdx1 hash=sha256:abcd */}\n",
+      "findings": [
+        {
+          "level": "warn",
+          "code": "HASH_DRIFT",
+          "id": "mdx1",
+          "line": 2
+        }
+      ],
+      "name": "lint-006"
+    },
+    {
+      "doc": "clean para.\n<!-- stay:ok -->\n\nanother.\n<!-- stay:ok2 -->\n",
+      "findings": [],
+      "name": "lint-007"
+    }
+  ]
+}