somnus-metadata 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- somnus_metadata-0.1.0/MANIFEST.in +19 -0
- somnus_metadata-0.1.0/PKG-INFO +82 -0
- somnus_metadata-0.1.0/README.md +70 -0
- somnus_metadata-0.1.0/pyproject.toml +39 -0
- somnus_metadata-0.1.0/setup.cfg +4 -0
- somnus_metadata-0.1.0/src/somnus/__init__.py +9 -0
- somnus_metadata-0.1.0/src/somnus/__main__.py +8 -0
- somnus_metadata-0.1.0/src/somnus/carriers/__init__.py +167 -0
- somnus_metadata-0.1.0/src/somnus/carriers/blockcomment.py +105 -0
- somnus_metadata-0.1.0/src/somnus/carriers/linecomment.py +109 -0
- somnus_metadata-0.1.0/src/somnus/carriers/markdown.py +106 -0
- somnus_metadata-0.1.0/src/somnus/carriers/sidecar.py +73 -0
- somnus_metadata-0.1.0/src/somnus/cli.py +169 -0
- somnus_metadata-0.1.0/src/somnus/commands/__init__.py +1 -0
- somnus_metadata-0.1.0/src/somnus/commands/_common.py +300 -0
- somnus_metadata-0.1.0/src/somnus/commands/brief.py +50 -0
- somnus_metadata-0.1.0/src/somnus/commands/bump.py +23 -0
- somnus_metadata-0.1.0/src/somnus/commands/check.py +48 -0
- somnus_metadata-0.1.0/src/somnus/commands/edit.py +18 -0
- somnus_metadata-0.1.0/src/somnus/commands/fork.py +89 -0
- somnus_metadata-0.1.0/src/somnus/commands/index.py +22 -0
- somnus_metadata-0.1.0/src/somnus/commands/init.py +41 -0
- somnus_metadata-0.1.0/src/somnus/commands/ls.py +20 -0
- somnus_metadata-0.1.0/src/somnus/commands/mcp.py +12 -0
- somnus_metadata-0.1.0/src/somnus/commands/migrate.py +406 -0
- somnus_metadata-0.1.0/src/somnus/commands/new.py +44 -0
- somnus_metadata-0.1.0/src/somnus/commands/query.py +28 -0
- somnus_metadata-0.1.0/src/somnus/commands/regions.py +57 -0
- somnus_metadata-0.1.0/src/somnus/commands/schema.py +85 -0
- somnus_metadata-0.1.0/src/somnus/commands/set_fields.py +52 -0
- somnus_metadata-0.1.0/src/somnus/commands/stale.py +67 -0
- somnus_metadata-0.1.0/src/somnus/commands/stamp.py +56 -0
- somnus_metadata-0.1.0/src/somnus/commands/status.py +36 -0
- somnus_metadata-0.1.0/src/somnus/config.py +176 -0
- somnus_metadata-0.1.0/src/somnus/db/__init__.py +5 -0
- somnus_metadata-0.1.0/src/somnus/db/schema.sql +175 -0
- somnus_metadata-0.1.0/src/somnus/db/store.py +682 -0
- somnus_metadata-0.1.0/src/somnus/document.py +334 -0
- somnus_metadata-0.1.0/src/somnus/ids.py +130 -0
- somnus_metadata-0.1.0/src/somnus/infer.py +145 -0
- somnus_metadata-0.1.0/src/somnus/mcp.py +304 -0
- somnus_metadata-0.1.0/src/somnus/model/__init__.py +1 -0
- somnus_metadata-0.1.0/src/somnus/model/jsonschema_export.py +122 -0
- somnus_metadata-0.1.0/src/somnus/model/lifecycle.py +114 -0
- somnus_metadata-0.1.0/src/somnus/model/schema.py +601 -0
- somnus_metadata-0.1.0/src/somnus/model/validate.py +844 -0
- somnus_metadata-0.1.0/src/somnus/model/vocab.py +75 -0
- somnus_metadata-0.1.0/src/somnus/output.py +92 -0
- somnus_metadata-0.1.0/src/somnus/regions.py +210 -0
- somnus_metadata-0.1.0/src/somnus/tui/__init__.py +1 -0
- somnus_metadata-0.1.0/src/somnus/tui/app.py +411 -0
- somnus_metadata-0.1.0/src/somnus/tui/form.py +162 -0
- somnus_metadata-0.1.0/src/somnus/tui/term.py +297 -0
- somnus_metadata-0.1.0/src/somnus/tui/widgets.py +350 -0
- somnus_metadata-0.1.0/src/somnus/yamlsub.py +759 -0
- somnus_metadata-0.1.0/src/somnus_metadata.egg-info/PKG-INFO +82 -0
- somnus_metadata-0.1.0/src/somnus_metadata.egg-info/SOURCES.txt +59 -0
- somnus_metadata-0.1.0/src/somnus_metadata.egg-info/dependency_links.txt +1 -0
- somnus_metadata-0.1.0/src/somnus_metadata.egg-info/entry_points.txt +2 -0
- somnus_metadata-0.1.0/src/somnus_metadata.egg-info/requires.txt +3 -0
- somnus_metadata-0.1.0/src/somnus_metadata.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Publish the toolkit, not the operator workspace or private research.
|
|
2
|
+
include pyproject.toml README.md
|
|
3
|
+
recursive-include src/somnus *.py *.sql
|
|
4
|
+
prune tests
|
|
5
|
+
prune archive
|
|
6
|
+
prune archives
|
|
7
|
+
prune docs
|
|
8
|
+
prune droid-wiki
|
|
9
|
+
prune runbooks
|
|
10
|
+
prune .codex
|
|
11
|
+
prune .claude
|
|
12
|
+
prune .factory
|
|
13
|
+
prune .github
|
|
14
|
+
prune .somnus-debug
|
|
15
|
+
prune .python_doctor
|
|
16
|
+
prune .python_doctor-src
|
|
17
|
+
exclude AGENTS*.md CONTEXT.md PLAN.md DECISIONS.md SPEC.md CONTRIBUTING.md
|
|
18
|
+
exclude last-session.txt workflows.md raw-tree.md production_doctor.log
|
|
19
|
+
global-exclude __pycache__ *.py[cod] .coverage .env .env.*
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: somnus-metadata
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Universal semantic metadata standard and engineering toolkit
|
|
5
|
+
Project-URL: Repository, https://github.com/calisweetleaf/somnus-metadata
|
|
6
|
+
Project-URL: Issues, https://github.com/calisweetleaf/somnus-metadata/issues
|
|
7
|
+
Keywords: metadata,markdown,cli,mcp,sqlite
|
|
8
|
+
Requires-Python: >=3.11
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
Provides-Extra: dev
|
|
11
|
+
Requires-Dist: mypy>=1.9; extra == "dev"
|
|
12
|
+
|
|
13
|
+
# somnus-metadata
|
|
14
|
+
|
|
15
|
+
The Somnus metadata standard (core `somnus://metadata/core/2.0.0`) and its stdlib-only toolkit.
|
|
16
|
+
|
|
17
|
+
Every managed file carries exactly one `somnus:` header. Markdown files use frontmatter or a hidden
|
|
18
|
+
comment envelope. Code and config files use a comment envelope. All other files use a
|
|
19
|
+
`<file>.somnus.yaml` sidecar. A global SQLite registry (`~/.somnus/somnus.db`) indexes identity,
|
|
20
|
+
revisions, relations, claims, and conflicts. It contains no JSON.
|
|
21
|
+
|
|
22
|
+
- Normative specification: [SPEC.md](SPEC.md)
|
|
23
|
+
- Ratified decisions: [DECISIONS.md](DECISIONS.md)
|
|
24
|
+
- Historical material (not normative): [archive/](archive/README.md)
|
|
25
|
+
|
|
26
|
+
## Install
|
|
27
|
+
|
|
28
|
+
Requires Python 3.11+ and has no third-party dependencies.
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
uv tool install somnus-metadata
|
|
32
|
+
somnus --version
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Alternatively, use `pipx install somnus-metadata`. For a Python virtual
|
|
36
|
+
environment, use `python -m pip install somnus-metadata`.
|
|
37
|
+
|
|
38
|
+
The distribution is **somnus-metadata**; the command and Python import remain
|
|
39
|
+
**somnus**. Do not install the unrelated PyPI distribution named `somnus` into
|
|
40
|
+
this same environment: it owns the same command/import names.
|
|
41
|
+
|
|
42
|
+
For development from a source checkout, use `uv tool install --editable .`.
|
|
43
|
+
The installed tool works outside this repository; register the project roots you
|
|
44
|
+
want to manage with `somnus init --root /path/to/project`.
|
|
45
|
+
|
|
46
|
+
Package release 0.1.0 implements metadata core 2.0.0. These are separate versions.
|
|
47
|
+
The CLI, terminal UI and stdio MCP adapter share one backend. A distributable
|
|
48
|
+
coding-agent plugin is not included in this release.
|
|
49
|
+
|
|
50
|
+
## Quick start
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
somnus init --root . # create ~/.somnus, config.toml, registry; register this root
|
|
54
|
+
somnus new specification "My Spec" # scaffold a conformant Markdown artifact
|
|
55
|
+
somnus check my-spec.md --level semantic
|
|
56
|
+
somnus stamp notes.py # dry-run diff; add --write to apply
|
|
57
|
+
somnus index # reconcile roots into the registry
|
|
58
|
+
somnus ls
|
|
59
|
+
somnus q --conflicts
|
|
60
|
+
somnus set my-spec.md "classification.tags=memory, design" # header edit, new revision
|
|
61
|
+
somnus edit # terminal UI
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
`somnus brief` prints an agent cheat sheet suitable for pasting into a repository's `AGENTS.md`.
|
|
65
|
+
|
|
66
|
+
## MCP server
|
|
67
|
+
|
|
68
|
+
`somnus mcp` serves non-interactive commands (excluding `edit` and `mcp` itself)
|
|
69
|
+
as Model Context Protocol tools over stdio.
|
|
70
|
+
Each tool returns the command's text output. Register it with any MCP client by command:
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
somnus mcp # optional: somnus --actor NAME mcp
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Exit codes: `0` ok, `1` validation errors, refusals, or conflicts, `2` usage or I/O errors.
|
|
77
|
+
|
|
78
|
+
## Tests
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
PYTHONPATH=src python -m unittest discover -s tests
|
|
82
|
+
```
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# somnus-metadata
|
|
2
|
+
|
|
3
|
+
The Somnus metadata standard (core `somnus://metadata/core/2.0.0`) and its stdlib-only toolkit.
|
|
4
|
+
|
|
5
|
+
Every managed file carries exactly one `somnus:` header. Markdown files use frontmatter or a hidden
|
|
6
|
+
comment envelope. Code and config files use a comment envelope. All other files use a
|
|
7
|
+
`<file>.somnus.yaml` sidecar. A global SQLite registry (`~/.somnus/somnus.db`) indexes identity,
|
|
8
|
+
revisions, relations, claims, and conflicts. It contains no JSON.
|
|
9
|
+
|
|
10
|
+
- Normative specification: [SPEC.md](SPEC.md)
|
|
11
|
+
- Ratified decisions: [DECISIONS.md](DECISIONS.md)
|
|
12
|
+
- Historical material (not normative): [archive/](archive/README.md)
|
|
13
|
+
|
|
14
|
+
## Install
|
|
15
|
+
|
|
16
|
+
Requires Python 3.11+ and has no third-party dependencies.
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
uv tool install somnus-metadata
|
|
20
|
+
somnus --version
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Alternatively, use `pipx install somnus-metadata`. For a Python virtual
|
|
24
|
+
environment, use `python -m pip install somnus-metadata`.
|
|
25
|
+
|
|
26
|
+
The distribution is **somnus-metadata**; the command and Python import remain
|
|
27
|
+
**somnus**. Do not install the unrelated PyPI distribution named `somnus` into
|
|
28
|
+
this same environment: it owns the same command/import names.
|
|
29
|
+
|
|
30
|
+
For development from a source checkout, use `uv tool install --editable .`.
|
|
31
|
+
The installed tool works outside this repository; register the project roots you
|
|
32
|
+
want to manage with `somnus init --root /path/to/project`.
|
|
33
|
+
|
|
34
|
+
Package release 0.1.0 implements metadata core 2.0.0. These are separate versions.
|
|
35
|
+
The CLI, terminal UI and stdio MCP adapter share one backend. A distributable
|
|
36
|
+
coding-agent plugin is not included in this release.
|
|
37
|
+
|
|
38
|
+
## Quick start
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
somnus init --root . # create ~/.somnus, config.toml, registry; register this root
|
|
42
|
+
somnus new specification "My Spec" # scaffold a conformant Markdown artifact
|
|
43
|
+
somnus check my-spec.md --level semantic
|
|
44
|
+
somnus stamp notes.py # dry-run diff; add --write to apply
|
|
45
|
+
somnus index # reconcile roots into the registry
|
|
46
|
+
somnus ls
|
|
47
|
+
somnus q --conflicts
|
|
48
|
+
somnus set my-spec.md "classification.tags=memory, design" # header edit, new revision
|
|
49
|
+
somnus edit # terminal UI
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`somnus brief` prints an agent cheat sheet suitable for pasting into a repository's `AGENTS.md`.
|
|
53
|
+
|
|
54
|
+
## MCP server
|
|
55
|
+
|
|
56
|
+
`somnus mcp` serves non-interactive commands (excluding `edit` and `mcp` itself)
|
|
57
|
+
as Model Context Protocol tools over stdio.
|
|
58
|
+
Each tool returns the command's text output. Register it with any MCP client by command:
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
somnus mcp # optional: somnus --actor NAME mcp
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Exit codes: `0` ok, `1` validation errors, refusals, or conflicts, `2` usage or I/O errors.
|
|
65
|
+
|
|
66
|
+
## Tests
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
PYTHONPATH=src python -m unittest discover -s tests
|
|
70
|
+
```
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68.0.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "somnus-metadata"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Universal semantic metadata standard and engineering toolkit"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
dependencies = []
|
|
12
|
+
|
|
13
|
+
keywords = ["metadata", "markdown", "cli", "mcp", "sqlite"]
|
|
14
|
+
|
|
15
|
+
[project.urls]
|
|
16
|
+
Repository = "https://github.com/calisweetleaf/somnus-metadata"
|
|
17
|
+
Issues = "https://github.com/calisweetleaf/somnus-metadata/issues"
|
|
18
|
+
|
|
19
|
+
[project.scripts]
|
|
20
|
+
somnus = "somnus.cli:main"
|
|
21
|
+
|
|
22
|
+
[project.optional-dependencies]
|
|
23
|
+
dev = ["mypy>=1.9"]
|
|
24
|
+
|
|
25
|
+
[tool.mypy]
|
|
26
|
+
python_version = "3.11"
|
|
27
|
+
mypy_path = "src"
|
|
28
|
+
files = ["src/somnus"]
|
|
29
|
+
check_untyped_defs = true
|
|
30
|
+
no_implicit_optional = true
|
|
31
|
+
warn_redundant_casts = true
|
|
32
|
+
warn_unused_ignores = true
|
|
33
|
+
warn_return_any = true
|
|
34
|
+
|
|
35
|
+
[tool.setuptools.packages.find]
|
|
36
|
+
where = ["src"]
|
|
37
|
+
|
|
38
|
+
[tool.setuptools.package-data]
|
|
39
|
+
"somnus.db" = ["schema.sql"]
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"""Somnus metadata system: schema constants and package version."""
|
|
2
|
+
|
|
3
|
+
__version__ = "0.1.0"
|
|
4
|
+
|
|
5
|
+
CORE_SCHEMA = "somnus://metadata/core/2.0.0"
|
|
6
|
+
SPEC_PROFILE = "somnus://metadata/profile/specification/1.0.0"
|
|
7
|
+
BENCHMARK_PROFILE = "somnus://metadata/profile/benchmark/1.0.0"
|
|
8
|
+
MIGRATION_EXTENSION = "somnus://metadata/extension/migration-v0.1/1.0.0"
|
|
9
|
+
DB_USER_VERSION = 1
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
"""Carrier protocol, registry, and extension-based auto-detection (SPEC §17).
|
|
2
|
+
|
|
3
|
+
A carrier works on a file's lines (without line endings). ``extract`` finds
|
|
4
|
+
the single authoritative envelope; ``render`` returns a splice that replaces
|
|
5
|
+
or inserts the envelope without touching any other line.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from dataclasses import dataclass, field
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
from typing import Optional, Protocol
|
|
13
|
+
|
|
14
|
+
SIDECAR_SUFFIX = ".somnus.yaml"
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
@dataclass
|
|
18
|
+
class Envelope:
|
|
19
|
+
"""Location of an envelope inside a file's lines (0-based, end exclusive)."""
|
|
20
|
+
|
|
21
|
+
kind: str
|
|
22
|
+
start: int
|
|
23
|
+
end: int
|
|
24
|
+
payload_lines: list[str]
|
|
25
|
+
payload_start: int # 0-based file line of the first payload line
|
|
26
|
+
col_offset: int = 0 # characters stripped from each payload line (prefix width)
|
|
27
|
+
mask_start: int = -1 # region scanning ignores [mask_start, mask_end)
|
|
28
|
+
mask_end: int = -1
|
|
29
|
+
|
|
30
|
+
def __post_init__(self) -> None:
|
|
31
|
+
if self.mask_start < 0:
|
|
32
|
+
self.mask_start, self.mask_end = self.start, self.end
|
|
33
|
+
|
|
34
|
+
@property
|
|
35
|
+
def payload(self) -> str:
|
|
36
|
+
"""Payload YAML text with a trailing newline."""
|
|
37
|
+
return "\n".join(self.payload_lines) + "\n"
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
@dataclass
|
|
41
|
+
class Issue:
|
|
42
|
+
"""Carrier-level problem at a 1-based file position."""
|
|
43
|
+
|
|
44
|
+
line: int
|
|
45
|
+
col: int
|
|
46
|
+
code: str
|
|
47
|
+
message: str
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
@dataclass
|
|
51
|
+
class Extraction:
|
|
52
|
+
"""Result of envelope extraction."""
|
|
53
|
+
|
|
54
|
+
envelope: Optional[Envelope] = None
|
|
55
|
+
issues: list[Issue] = field(default_factory=list)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
@dataclass
|
|
59
|
+
class Splice:
|
|
60
|
+
"""Replace ``lines[start:end]`` with ``new_lines``."""
|
|
61
|
+
|
|
62
|
+
start: int
|
|
63
|
+
end: int
|
|
64
|
+
new_lines: list[str]
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
class Carrier(Protocol):
|
|
68
|
+
"""Interface implemented by every carrier."""
|
|
69
|
+
|
|
70
|
+
name: str
|
|
71
|
+
capability: str
|
|
72
|
+
forbid: Optional[str]
|
|
73
|
+
region_style: tuple
|
|
74
|
+
|
|
75
|
+
def extract(self, lines: list[str]) -> Extraction:
|
|
76
|
+
"""Locate the envelope."""
|
|
77
|
+
...
|
|
78
|
+
|
|
79
|
+
def render(self, lines: list[str], payload: str, envelope: Optional[Envelope], style: Optional[str] = None) -> Splice:
|
|
80
|
+
"""Return the splice that writes ``payload`` into the file."""
|
|
81
|
+
...
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
class CarrierError(ValueError):
|
|
85
|
+
"""The carrier cannot place the envelope without altering host semantics."""
|
|
86
|
+
|
|
87
|
+
def __init__(self, code: str, message: str, line: int = 1):
|
|
88
|
+
self.code = code
|
|
89
|
+
self.line = line
|
|
90
|
+
super().__init__(message)
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def _registry() -> dict[str, Carrier]:
|
|
94
|
+
from somnus.carriers.blockcomment import CSS, XML
|
|
95
|
+
from somnus.carriers.linecomment import HashCarrier, LineCarrier
|
|
96
|
+
from somnus.carriers.markdown import MarkdownCarrier
|
|
97
|
+
|
|
98
|
+
return {
|
|
99
|
+
"markdown": MarkdownCarrier(),
|
|
100
|
+
"python": HashCarrier("python"),
|
|
101
|
+
"shell": HashCarrier("shell"),
|
|
102
|
+
"powershell": HashCarrier("powershell"),
|
|
103
|
+
"r": HashCarrier("r"),
|
|
104
|
+
"toml": HashCarrier("toml"),
|
|
105
|
+
"yaml": HashCarrier("yaml"),
|
|
106
|
+
"tex": LineCarrier("tex", "% ", "somnus-adapter-tex@1", "tex"),
|
|
107
|
+
"slash": LineCarrier("slash", "// ", "somnus-adapter-slash-comment@1", "slash"),
|
|
108
|
+
"js": LineCarrier("js", "// ", "somnus-adapter-slash-comment@1", "js"),
|
|
109
|
+
"sql": LineCarrier("sql", "-- ", "somnus-adapter-sql-comment@1", "sql"),
|
|
110
|
+
"css": CSS,
|
|
111
|
+
"xml": XML,
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
EXTENSIONS: dict[str, str] = {
|
|
116
|
+
".md": "markdown", ".markdown": "markdown", ".mdx": "markdown",
|
|
117
|
+
".py": "python", ".pyw": "python",
|
|
118
|
+
".sh": "shell", ".bash": "shell", ".zsh": "shell",
|
|
119
|
+
".ps1": "powershell", ".psm1": "powershell", ".psd1": "powershell",
|
|
120
|
+
".r": "r",
|
|
121
|
+
".toml": "toml", ".yaml": "yaml", ".yml": "yaml",
|
|
122
|
+
".tex": "tex", ".sty": "tex", ".cls": "tex", ".ltx": "tex",
|
|
123
|
+
".js": "js", ".mjs": "js", ".cjs": "js", ".jsx": "js", ".ts": "js", ".tsx": "js",
|
|
124
|
+
".rs": "slash", ".c": "slash", ".h": "slash", ".cc": "slash", ".cpp": "slash", ".hpp": "slash",
|
|
125
|
+
".go": "slash", ".java": "slash", ".kt": "slash", ".swift": "slash", ".cs": "slash",
|
|
126
|
+
".sql": "sql",
|
|
127
|
+
".css": "css", ".scss": "css", ".less": "css",
|
|
128
|
+
".html": "xml", ".htm": "xml", ".xhtml": "xml", ".xml": "xml", ".svg": "xml",
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
_CACHE: dict[str, Carrier] = {}
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def get(name: str) -> Carrier:
|
|
135
|
+
"""Return the carrier registered under ``name``."""
|
|
136
|
+
if not _CACHE:
|
|
137
|
+
_CACHE.update(_registry())
|
|
138
|
+
return _CACHE[name]
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def is_sidecar_path(path: Path) -> bool:
|
|
142
|
+
"""Return True for ``*.somnus.yaml`` sidecar files."""
|
|
143
|
+
return path.name.endswith(SIDECAR_SUFFIX)
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def sidecar_for(path: Path) -> Path:
|
|
147
|
+
"""Return the sidecar path for a host file."""
|
|
148
|
+
return path.with_name(path.name + SIDECAR_SUFFIX)
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def host_for(sidecar: Path) -> Path:
|
|
152
|
+
"""Return the host path a sidecar file describes by name."""
|
|
153
|
+
return sidecar.with_name(sidecar.name[: -len(SIDECAR_SUFFIX)])
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def carrier_name_for(path: Path) -> Optional[str]:
|
|
157
|
+
"""Return the embedded carrier name for a path, or None when a sidecar is required."""
|
|
158
|
+
if is_sidecar_path(path):
|
|
159
|
+
return None
|
|
160
|
+
suffix = path.suffix if path.suffix in EXTENSIONS else path.suffix.lower()
|
|
161
|
+
return EXTENSIONS.get(suffix)
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
def for_path(path: Path) -> Optional[Carrier]:
|
|
165
|
+
"""Return the embedded carrier for a path, or None when a sidecar is required."""
|
|
166
|
+
name = carrier_name_for(path)
|
|
167
|
+
return get(name) if name else None
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
"""Block-comment carriers: CSS ``/* */`` and XML/HTML/SVG ``<!-- -->`` (SPEC §17.4–§17.5)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
from typing import Optional
|
|
7
|
+
|
|
8
|
+
from somnus.carriers import CarrierError, Envelope, Extraction, Issue, Splice
|
|
9
|
+
|
|
10
|
+
_CHARSET = re.compile(r'^@charset "[^"]*";\s*$')
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class BlockCarrier:
|
|
14
|
+
"""Envelope delimited by a block-comment opener and closer line."""
|
|
15
|
+
|
|
16
|
+
def __init__(self, name: str, opener: str, closer: str, forbidden: str, forbid: str, region_style: tuple):
|
|
17
|
+
self.name = name
|
|
18
|
+
self.capability = "somnus-adapter-block-comment@1"
|
|
19
|
+
self.opener = opener
|
|
20
|
+
self.closer = closer
|
|
21
|
+
self.forbidden = forbidden
|
|
22
|
+
self.forbid: Optional[str] = forbid
|
|
23
|
+
self.region_style = region_style
|
|
24
|
+
|
|
25
|
+
def preamble_end(self, lines: list[str]) -> int:
|
|
26
|
+
"""Return the index after the host's mandatory leading declarations."""
|
|
27
|
+
i = 0
|
|
28
|
+
if self.name == "css":
|
|
29
|
+
if lines and lines[0].startswith("@charset"):
|
|
30
|
+
if not _CHARSET.match(lines[0]):
|
|
31
|
+
raise CarrierError("E_HOST", "@charset declaration must be alone on the first line", 1)
|
|
32
|
+
i = 1
|
|
33
|
+
return i
|
|
34
|
+
while i < len(lines):
|
|
35
|
+
stripped = lines[i].lstrip()
|
|
36
|
+
if stripped.startswith("<?xml"):
|
|
37
|
+
if "?>" not in stripped:
|
|
38
|
+
raise CarrierError("E_HOST", "multi-line XML declaration cannot be preserved safely", i + 1)
|
|
39
|
+
i += 1
|
|
40
|
+
elif stripped[:9].upper() == "<!DOCTYPE":
|
|
41
|
+
if ">" not in stripped:
|
|
42
|
+
raise CarrierError("E_HOST", "multi-line DOCTYPE cannot be preserved safely", i + 1)
|
|
43
|
+
i += 1
|
|
44
|
+
else:
|
|
45
|
+
break
|
|
46
|
+
return i
|
|
47
|
+
|
|
48
|
+
def _skippable(self, line: str) -> bool:
|
|
49
|
+
s = line.strip()
|
|
50
|
+
if not s:
|
|
51
|
+
return True
|
|
52
|
+
if self.name == "xml":
|
|
53
|
+
return s.startswith("<!--") and s.endswith("-->") and s != self.opener
|
|
54
|
+
return s.startswith("/*") and s.endswith("*/") and s != self.opener
|
|
55
|
+
|
|
56
|
+
def extract(self, lines: list[str]) -> Extraction:
|
|
57
|
+
"""Scan the leading area (after declarations) for one envelope."""
|
|
58
|
+
result = Extraction()
|
|
59
|
+
try:
|
|
60
|
+
i = self.preamble_end(lines)
|
|
61
|
+
except CarrierError:
|
|
62
|
+
i = 0
|
|
63
|
+
found: list[Envelope] = []
|
|
64
|
+
n = len(lines)
|
|
65
|
+
while i < n:
|
|
66
|
+
if lines[i].rstrip() == self.opener:
|
|
67
|
+
j = i + 1
|
|
68
|
+
while j < n and lines[j].rstrip() != self.closer:
|
|
69
|
+
j += 1
|
|
70
|
+
if j >= n:
|
|
71
|
+
result.issues.append(Issue(i + 1, 1, "E_ENVELOPE", "metadata envelope is never closed"))
|
|
72
|
+
break
|
|
73
|
+
payload = lines[i + 1 : j]
|
|
74
|
+
for k, text in enumerate(payload):
|
|
75
|
+
if self.forbidden in text:
|
|
76
|
+
result.issues.append(Issue(i + 2 + k, text.index(self.forbidden) + 1, "E_ENVELOPE",
|
|
77
|
+
f"{self.forbidden!r} is forbidden inside this envelope"))
|
|
78
|
+
found.append(Envelope(self.name, i, j + 1, payload, i + 1))
|
|
79
|
+
i = j + 1
|
|
80
|
+
continue
|
|
81
|
+
if self._skippable(lines[i]):
|
|
82
|
+
i += 1
|
|
83
|
+
continue
|
|
84
|
+
break
|
|
85
|
+
for extra in found[1:]:
|
|
86
|
+
result.issues.append(Issue(extra.start + 1, 1, "E_ENVELOPE", "more than one metadata envelope"))
|
|
87
|
+
if found:
|
|
88
|
+
result.envelope = found[0]
|
|
89
|
+
return result
|
|
90
|
+
|
|
91
|
+
def render(self, lines: list[str], payload: str, envelope: Optional[Envelope], style: Optional[str] = None) -> Splice:
|
|
92
|
+
"""Replace the envelope, or insert it after the leading declarations."""
|
|
93
|
+
body = payload.rstrip("\n").split("\n")
|
|
94
|
+
for k, text in enumerate(body):
|
|
95
|
+
if self.forbidden in text:
|
|
96
|
+
raise CarrierError("E_HOST", f"payload contains {self.forbidden!r}; use a sidecar", k + 1)
|
|
97
|
+
block = [self.opener, *body, self.closer]
|
|
98
|
+
if envelope is not None:
|
|
99
|
+
return Splice(envelope.start, envelope.end, block)
|
|
100
|
+
at = self.preamble_end(lines)
|
|
101
|
+
return Splice(at, at, block)
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
CSS = BlockCarrier("css", "/* somnus:metadata:v2", "somnus:end */", "*/", "block", ("block", "/* ", " */"))
|
|
105
|
+
XML = BlockCarrier("xml", "<!-- somnus:metadata:v2", "somnus:end -->", "--", "html", ("markdown",))
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
"""Comment-prefixed carriers: ``# ``, ``% ``, ``// ``, ``-- `` (SPEC §17.3, §17.5)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
from typing import Optional
|
|
7
|
+
|
|
8
|
+
from somnus.carriers import Envelope, Extraction, Issue, Splice
|
|
9
|
+
|
|
10
|
+
_COOKIE = re.compile(r"^[ \t\f]*#.*?coding[:=][ \t]*[-\w.]+")
|
|
11
|
+
_REQUIRES = re.compile(r"^#requires\b", re.IGNORECASE)
|
|
12
|
+
_TEX_MAGIC = re.compile(r"^%\s*!tex\b", re.IGNORECASE)
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def preamble_end(host: str, lines: list[str]) -> int:
|
|
16
|
+
"""Return the index of the first line after mandatory host preamble lines."""
|
|
17
|
+
i = 0
|
|
18
|
+
n = len(lines)
|
|
19
|
+
if host in ("python", "shell", "r", "js", "powershell") and n and lines[0].startswith("#!"):
|
|
20
|
+
i = 1
|
|
21
|
+
if host == "python":
|
|
22
|
+
if i == 0 and n and _COOKIE.match(lines[0]):
|
|
23
|
+
i = 1
|
|
24
|
+
elif n > 1 and lines[0].lstrip().startswith("#") and _COOKIE.match(lines[1]):
|
|
25
|
+
i = 2
|
|
26
|
+
elif host == "powershell":
|
|
27
|
+
while i < n and _REQUIRES.match(lines[i]):
|
|
28
|
+
i += 1
|
|
29
|
+
elif host == "tex":
|
|
30
|
+
while i < n and _TEX_MAGIC.match(lines[i]):
|
|
31
|
+
i += 1
|
|
32
|
+
return i
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class LineCarrier:
|
|
36
|
+
"""Envelope made of prefixed comment lines in the host's leading comment area."""
|
|
37
|
+
|
|
38
|
+
forbid: Optional[str] = None
|
|
39
|
+
|
|
40
|
+
def __init__(self, host: str, prefix: str, capability: str, name: Optional[str] = None):
|
|
41
|
+
self.host = host
|
|
42
|
+
self.prefix = prefix
|
|
43
|
+
self.bare = prefix.rstrip()
|
|
44
|
+
self.capability = capability
|
|
45
|
+
self.name = name or host
|
|
46
|
+
self.opener = f"{prefix}somnus:metadata:v2"
|
|
47
|
+
self.closer = f"{prefix}somnus:end"
|
|
48
|
+
self.region_style = ("prefix", prefix)
|
|
49
|
+
|
|
50
|
+
def _is_comment(self, line: str) -> bool:
|
|
51
|
+
return line.lstrip().startswith(self.bare)
|
|
52
|
+
|
|
53
|
+
def extract(self, lines: list[str]) -> Extraction:
|
|
54
|
+
"""Scan the leading comment area for exactly one envelope."""
|
|
55
|
+
result = Extraction()
|
|
56
|
+
found: list[Envelope] = []
|
|
57
|
+
i = preamble_end(self.host, lines)
|
|
58
|
+
n = len(lines)
|
|
59
|
+
while i < n:
|
|
60
|
+
line = lines[i]
|
|
61
|
+
if line.rstrip() == self.opener.rstrip():
|
|
62
|
+
j = i + 1
|
|
63
|
+
payload: list[str] = []
|
|
64
|
+
ok = True
|
|
65
|
+
while j < n and lines[j].rstrip() != self.closer.rstrip():
|
|
66
|
+
text = lines[j]
|
|
67
|
+
if text.rstrip() == self.bare:
|
|
68
|
+
payload.append("")
|
|
69
|
+
elif text.startswith(self.prefix):
|
|
70
|
+
payload.append(text[len(self.prefix):])
|
|
71
|
+
else:
|
|
72
|
+
result.issues.append(Issue(j + 1, 1, "E_ENVELOPE",
|
|
73
|
+
f"envelope line must start with {self.prefix!r}"))
|
|
74
|
+
ok = False
|
|
75
|
+
break
|
|
76
|
+
j += 1
|
|
77
|
+
if ok and j >= n:
|
|
78
|
+
result.issues.append(Issue(i + 1, 1, "E_ENVELOPE", "metadata envelope is never closed"))
|
|
79
|
+
break
|
|
80
|
+
if not ok:
|
|
81
|
+
break
|
|
82
|
+
found.append(Envelope(self.name, i, j + 1, payload, i + 1, len(self.prefix)))
|
|
83
|
+
i = j + 1
|
|
84
|
+
continue
|
|
85
|
+
if not line.strip() or self._is_comment(line):
|
|
86
|
+
i += 1
|
|
87
|
+
continue
|
|
88
|
+
break
|
|
89
|
+
for extra in found[1:]:
|
|
90
|
+
result.issues.append(Issue(extra.start + 1, 1, "E_ENVELOPE", "more than one metadata envelope"))
|
|
91
|
+
if found:
|
|
92
|
+
result.envelope = found[0]
|
|
93
|
+
return result
|
|
94
|
+
|
|
95
|
+
def render(self, lines: list[str], payload: str, envelope: Optional[Envelope], style: Optional[str] = None) -> Splice:
|
|
96
|
+
"""Replace the envelope, or insert it right after the mandatory preamble."""
|
|
97
|
+
body = [self.prefix + ln if ln else self.prefix for ln in payload.rstrip("\n").split("\n")]
|
|
98
|
+
block = [self.opener, *body, self.closer]
|
|
99
|
+
if envelope is not None:
|
|
100
|
+
return Splice(envelope.start, envelope.end, block)
|
|
101
|
+
at = preamble_end(self.host, lines)
|
|
102
|
+
return Splice(at, at, block)
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
class HashCarrier(LineCarrier):
|
|
106
|
+
"""``# `` carrier for Python, shell, PowerShell, R, TOML, and YAML hosts."""
|
|
107
|
+
|
|
108
|
+
def __init__(self, host: str):
|
|
109
|
+
super().__init__(host, "# ", "somnus-adapter-hash-comment@1", host)
|