jqpm 0.1.0__py3-none-any.whl

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.
@@ -0,0 +1,243 @@
1
+ Metadata-Version: 2.4
2
+ Name: jqpm
3
+ Version: 0.1.0
4
+ Summary: A minimal package manager for jq
5
+ Author: Miguel Ceriani
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/miguel76/jqpm
8
+ Project-URL: Issues, https://github.com/miguel76/jqpm/issues
9
+ Keywords: jq,package-manager,json
10
+ Classifier: Environment :: Console
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Topic :: Software Development :: Build Tools
14
+ Requires-Python: >=3.9
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE
17
+ Dynamic: license-file
18
+
19
+ # jqpm — a minimal package manager for jq
20
+
21
+ `jqpm` lets you declare, install, and pin `jq` module dependencies from git
22
+ repos (GitHub by default), the same way `npm`/`cargo`/`pip` manage
23
+ dependencies — but radically simpler, because **jq already has a module
24
+ system**. `jqpm` doesn't reinvent that; it just fetches git repos into the
25
+ exact folder layout jq's own `import` resolution already looks for.
26
+
27
+ This means once a package is installed, you use it with **plain, unmodified
28
+ `jq`** — no custom loader, no wrapper required at runtime:
29
+
30
+ ```sh
31
+ jq -L jq_modules 'import "owner/repo" as X; X::somefunc' input.json
32
+ ```
33
+
34
+ ## Prior art
35
+
36
+ This is directly inspired by [jqnpm](https://github.com/jqnpm/jqnpm)
37
+ (2014–2021, now archived) — same idea of GitHub-namespaced packages
38
+ (`owner/repo`) and semver git tags. `jqpm` differs mainly in that it doesn't
39
+ wrap `jq` at all at runtime; it leans entirely on jq's native `-L` search
40
+ path and `import "owner/repo"` resolution, so the "package manager" part
41
+ of the system is only responsible for *fetching*, not *loading*.
42
+
43
+ ## Install
44
+
45
+ Requires Python 3.9+, `git`, and `jq` (1.6+ recommended for reliable
46
+ `import`) on your `PATH`.
47
+
48
+ The easiest way is from PyPI, which puts a `jqpm` command on your `PATH`:
49
+
50
+ ```sh
51
+ pipx install jqpm # or: uv tool install jqpm
52
+ ```
53
+
54
+ Alternatively, it's a single file with no dependencies, attached to every
55
+ [GitHub release](https://github.com/miguel76/jqpm/releases):
56
+
57
+ ```sh
58
+ curl -fLO https://github.com/miguel76/jqpm/releases/latest/download/jqpm.py
59
+ chmod +x jqpm.py
60
+ # optionally: sudo ln -s $(pwd)/jqpm.py /usr/local/bin/jqpm
61
+ ```
62
+
63
+ To pin a specific version, replace `latest/download` with
64
+ `download/v0.1.0` (or any other release tag).
65
+
66
+ ## Releasing
67
+
68
+ 1. Bump `__version__` in `jqpm.py` and commit.
69
+ 2. Create a GitHub release with a matching tag (e.g. `v0.1.0`).
70
+
71
+ The [release workflow](.github/workflows/release.yml) then runs the tests,
72
+ attaches `jqpm.py` to the release, and publishes the package to PyPI.
73
+
74
+ ## Package convention
75
+
76
+ A package is just a git repo named `repo`, owned by `owner` on GitHub,
77
+ containing a file `repo.jq` at its root (this matches jq's own module
78
+ naming rules: `import "owner/repo"` looks for `owner/repo.jq` or
79
+ `owner/repo/repo.jq` on the search path — jqpm uses the latter).
80
+
81
+ ```
82
+ my-jq-lib/
83
+ my-jq-lib.jq # the entry point, this is what gets imported
84
+ README.md
85
+ ```
86
+
87
+ Nothing else is required — no manifest inside the package itself. Tag
88
+ releases with semver git tags (`v1.2.0` or `1.2.0`).
89
+
90
+ ### Multi-file packages
91
+
92
+ The entry file doesn't have to hold all the code. It can `import`/`include`
93
+ other `.jq`/`.json` files shipped in the same repo, directly or indirectly
94
+ (A imports B, B imports C, ...), exactly like Python or JS:
95
+
96
+ - a spec starting with `./` or `../` is a **local** import — resolved
97
+ relative to the file that contains it, and installed together with the
98
+ package;
99
+ - anything else, e.g. `import "owner/repo" as X;`, is **package-manager-mediated**
100
+ — resolved by jq itself via `-L jq_modules`, same as always.
101
+
102
+ ```
103
+ my-jq-lib/
104
+ my-jq-lib.jq # import "./internal/parse" as P; ...
105
+ internal/
106
+ parse.jq # import "./format" as F; ... (reaches a sibling)
107
+ format.jq
108
+ ```
109
+
110
+ Plain jq resolves `./`-imports relative to the process's current directory,
111
+ not to the file that contains them — which breaks the moment a package
112
+ with local imports is installed under `jq_modules/owner/repo/` and used
113
+ from a different project's directory. jqpm works around this at `jqpm
114
+ install` time by rewriting each local spec into its fully-qualified
115
+ `owner/repo/...` form, still plain jq module names resolved via `-L`, no
116
+ runtime loader involved.
117
+
118
+ ### Transitive dependencies
119
+
120
+ A package can depend on other packages too: just ship a `jqpackage.json`
121
+ at its root declaring its own `dependencies`, same format as a project's
122
+ manifest. `jqpm install` walks that graph automatically — every
123
+ dependency of every installed package is fetched and flattened into the
124
+ consuming project's own `jq_modules/`, right alongside its direct
125
+ dependencies:
126
+
127
+ ```
128
+ jq_modules/
129
+ acme/
130
+ mid/ # a direct dependency of your project
131
+ mid.jq
132
+ jqpackage.json # declares acme/base as its own dependency
133
+ base/ # fetched automatically because mid depends on it
134
+ base.jq
135
+ ```
136
+
137
+ This has to be a flat layout rather than a nested one, because jq's own
138
+ `import` resolution only ever searches a single `-L` path — there's no
139
+ such thing as a package-scoped `jq_modules` the way there is with, say,
140
+ `node_modules`.
141
+
142
+ If two packages require different versions of the same dependency, jqpm
143
+ resolves it like this:
144
+
145
+ - a dependency declared directly in *your* `jqpackage.json` always wins
146
+ over anything merely inferred transitively;
147
+ - between two transitive requirements, the one resolving to the higher
148
+ semver tag wins;
149
+ - a conflict jqpm can't order (e.g. two different explicit git refs) is a
150
+ hard error telling you to add an explicit top-level dependency in your
151
+ own `jqpackage.json` to pin it.
152
+
153
+ `jqpackage-lock.json` covers the whole flattened graph, not just your
154
+ direct dependencies, so `jqpm install` (without `--update`) is reproducible
155
+ end to end; `jqpm list` marks which entries are transitive and shows what
156
+ pulled each one in.
157
+
158
+ ## Usage
159
+
160
+ ```sh
161
+ # start a new project
162
+ jqpm init
163
+
164
+ # add a dependency (resolves the latest tag satisfying the range,
165
+ # writes it to jqpackage.json, installs it, and records the exact
166
+ # commit in jqpackage-lock.json)
167
+ jqpm add someuser/jq-strings@^1.0.0
168
+
169
+ # install everything from jqpackage.json
170
+ # (reproducible: reuses the exact commit from jqpackage-lock.json
171
+ # if present, so installs are pinned until you explicitly update)
172
+ jqpm install
173
+
174
+ # re-resolve all versions against latest matching tags
175
+ jqpm install --update
176
+
177
+ # see what's installed and at what commit
178
+ jqpm list
179
+
180
+ # remove a dependency
181
+ jqpm remove someuser/jq-strings
182
+
183
+ # run jq with -L jq_modules already set, so imports just work
184
+ jqpm run -n 'import "someuser/jq-strings" as S; "hi" | S::upper'
185
+ ```
186
+
187
+ Or skip `jqpm run` entirely and call `jq -L jq_modules ...` yourself —
188
+ that's the whole point of piggybacking on jq's native module resolution.
189
+
190
+ ## Version specs
191
+
192
+ Matched against the package repo's git tags:
193
+
194
+ | spec | meaning |
195
+ |--------------|-------------------------------------------------|
196
+ | `1.2.3` | exact tag (`v1.2.3` or `1.2.3`) |
197
+ | `^1.2.3` | latest `1.x.x` >= `1.2.3` |
198
+ | `~1.2.3` | latest `1.2.x` >= `1.2.3` |
199
+ | `*` (default)| latest tag, or default branch `HEAD` if no tags |
200
+ | `#some-ref` | exact git ref: branch name, tag, or commit sha |
201
+
202
+ ## Files
203
+
204
+ - `jqpackage.json` — manifest: name, version, dependencies (checked in)
205
+ - `jqpackage-lock.json` — resolved commit per dependency (checked in, for
206
+ reproducible installs — same idea as `package-lock.json`/`Cargo.lock`)
207
+ - `jq_modules/` — installed packages, laid out as `jq_modules/owner/repo/repo.jq`
208
+ (gitignore this, like `node_modules/`)
209
+
210
+ ## Testing
211
+
212
+ ```sh
213
+ pip install -r requirements-dev.txt
214
+ pytest
215
+ ```
216
+
217
+ The test suite doesn't touch GitHub or the network: it builds throwaway git
218
+ repos on disk (with real tags) and points jqpm at them via `file://` URLs,
219
+ so it exercises the real `git clone`/`ls-remote`/`checkout` codepath end to
220
+ end without any external test fixtures to host or maintain.
221
+
222
+ ## What's deliberately left out (v0)
223
+
224
+ This is intentionally minimal. Not included yet, roughly in order of
225
+ likely usefulness:
226
+
227
+ - **A real registry / search.** Right now "the registry" is just "GitHub,
228
+ addressed by `owner/repo`." A `jqpm search` would need a real index
229
+ (could start as a static JSON file in a shared repo, à la early
230
+ Bower/npm-before-npm).
231
+ - **Integrity checking.** The lockfile records a commit sha (which is
232
+ already tamper-evident for that repo's history) but doesn't verify
233
+ signatures or checksums of the fetched tree.
234
+ - **`jqpm publish`.** Publishing today is just "push a git tag." A
235
+ `publish` command could automate tagging/pushing and maybe validate
236
+ that `repo.jq` exists and parses.
237
+ - **A real "private registry" concept**, though any git host already works
238
+ today: `jqpm add https://gitlab.example.com/team/jq-lib.git@^1.0.0`
239
+ installs the same way as a GitHub `owner/repo` dependency.
240
+
241
+ ## License
242
+
243
+ Public domain / do whatever you want with it — it's a starting point.
@@ -0,0 +1,7 @@
1
+ jqpm.py,sha256=7PwaTj5PT7277-qQoZxMj8CsUtcdxqwKzlu6QKXk65Y,23288
2
+ jqpm-0.1.0.dist-info/licenses/LICENSE,sha256=GcEAlR8BP82IIb2IblcXFiwHaiVFPkmkL4R2isIofZ8,1071
3
+ jqpm-0.1.0.dist-info/METADATA,sha256=ii7liARL6plLTto9KUtNSQkXNBCw4wI7JpWgMY8cXVc,9037
4
+ jqpm-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
5
+ jqpm-0.1.0.dist-info/entry_points.txt,sha256=C0LWXY0-AqRmc6mxOgyyddyzvDMvJXpz6pagnYk1qYE,35
6
+ jqpm-0.1.0.dist-info/top_level.txt,sha256=faNwCB72AefMXrg23Uzt-yJViTR5P2tya0yOXtzz-ko,5
7
+ jqpm-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ jqpm = jqpm:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Miguel Ceriani
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ jqpm
jqpm.py ADDED
@@ -0,0 +1,617 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ jqpm -- a minimal package manager for jq
4
+
5
+ Design in one sentence: jqpm's only job is to fetch git repos into the
6
+ folder layout jq *already* knows how to `import` from (via `-L`), so no
7
+ custom module loader or jq wrapper is required at runtime.
8
+
9
+ Convention
10
+ ----------
11
+ A "package" is just a git repo, referenced as `owner/repo` (GitHub by
12
+ default, but any git URL works). jqpm clones it into:
13
+
14
+ jq_modules/<owner>/<repo>/<repo>.jq
15
+
16
+ which matches jq's native module resolution: `import "owner/repo" as X;`
17
+ with `-L jq_modules` on the command line will find exactly that file
18
+ (jq looks for `<search-path>/owner/repo.jq` or
19
+ `<search-path>/owner/repo/repo.jq` -- we use the latter).
20
+
21
+ So once installed, a package is used with **plain jq**, no wrapper needed:
22
+
23
+ jq -L jq_modules 'import "owner/repo" as X; X::somefunc' input.json
24
+
25
+ `jqpm run` is just a convenience that adds `-L jq_modules` for you.
26
+
27
+ Manifest: jqpackage.json (like package.json)
28
+ Lockfile: jqpackage-lock.json (resolved commit per dependency)
29
+
30
+ Version specs (matched against git tags, tags may be "v1.2.3" or "1.2.3"):
31
+ "1.2.3" exact tag
32
+ "^1.2.3" latest 1.x.x >= 1.2.3
33
+ "~1.2.3" latest 1.2.x >= 1.2.3
34
+ "*" latest tag (or default branch HEAD if no tags)
35
+ "#<ref>" exact git ref / branch / commit sha
36
+
37
+ Multi-file packages
38
+ --------------------
39
+ A package's entry file (`<repo>.jq`) may `import`/`include` other `.jq`/
40
+ `.json` files that live in the same repo, exactly like Python or JS: a spec
41
+ starting with `./` or `../` is a *local* import, resolved relative to the
42
+ file that contains it, and is shipped and installed together with the
43
+ package. Anything else (e.g. `import "owner/repo" as X;`) is *package-manager-mediated*: resolved by jq itself via `-L jq_modules`, unchanged.
44
+
45
+ jq's own `import`/`include` resolve `./` paths relative to the process's
46
+ cwd, not to the file that contains them -- which breaks as soon as a
47
+ package with local imports is installed under `jq_modules/owner/repo/`
48
+ and used from a different project. jqpm works around this at install time
49
+ by rewriting each local spec into its fully-qualified `owner/repo/...`
50
+ form (still resolved by plain jq via `-L`, no runtime shim needed).
51
+
52
+ Transitive dependencies
53
+ ------------------------
54
+ A package may itself ship a `jqpackage.json` at its root declaring its own
55
+ `dependencies`, using the same manifest format as a project. `jqpm install`
56
+ walks that graph: every dependency of every installed package is fetched
57
+ too, flattened into the same top-level `jq_modules/` (jq's own `import`
58
+ only ever searches one `-L` path, so there's no such thing as a "nested"
59
+ jq_modules -- flattening is required, not a choice).
60
+
61
+ Conflict resolution, when two packages require different versions of the
62
+ same dependency:
63
+ - a dependency declared directly in the *project's own* jqpackage.json
64
+ always wins over any transitively-inferred requirement;
65
+ - between two transitive requirements, the one resolving to the higher
66
+ semver tag wins;
67
+ - a conflict jqpm can't order (an explicit git ref/branch/sha clashing
68
+ with anything else) is a hard error asking the user to add an explicit
69
+ top-level dependency to pin it.
70
+ """
71
+
72
+ import argparse
73
+ import json
74
+ import os
75
+ import posixpath
76
+ import re
77
+ import subprocess
78
+ import sys
79
+ from pathlib import Path
80
+
81
+ __version__ = "0.1.0"
82
+
83
+ MANIFEST = "jqpackage.json"
84
+ LOCKFILE = "jqpackage-lock.json"
85
+ MODULES_DIR = "jq_modules"
86
+
87
+ # --------------------------------------------------------------------------
88
+ # small helpers
89
+ # --------------------------------------------------------------------------
90
+
91
+ def die(msg):
92
+ print(f"jqpm: error: {msg}", file=sys.stderr)
93
+ sys.exit(1)
94
+
95
+
96
+ def run(cmd, cwd=None, capture=True, check=True):
97
+ result = subprocess.run(
98
+ cmd, cwd=cwd,
99
+ stdout=subprocess.PIPE if capture else None,
100
+ stderr=subprocess.PIPE if capture else None,
101
+ text=True,
102
+ )
103
+ if check and result.returncode != 0:
104
+ stderr = result.stderr if capture else ""
105
+ die(f"command failed: {' '.join(cmd)}\n{stderr}")
106
+ return result
107
+
108
+
109
+ def load_json(path, default=None):
110
+ p = Path(path)
111
+ if not p.exists():
112
+ return default
113
+ with open(p) as f:
114
+ return json.load(f)
115
+
116
+
117
+ def save_json(path, data):
118
+ with open(path, "w") as f:
119
+ json.dump(data, f, indent=2)
120
+ f.write("\n")
121
+
122
+
123
+ def load_manifest():
124
+ m = load_json(MANIFEST)
125
+ if m is None:
126
+ die(f"no {MANIFEST} found here. Run `jqpm init` first.")
127
+ assert m is not None
128
+ m.setdefault("dependencies", {})
129
+ return m
130
+
131
+
132
+ # --------------------------------------------------------------------------
133
+ # spec / version parsing
134
+ # --------------------------------------------------------------------------
135
+
136
+ SEMVER_RE = re.compile(r"^v?(\d+)\.(\d+)\.(\d+)")
137
+
138
+
139
+ def semver_tuple(tag):
140
+ match = SEMVER_RE.match(tag)
141
+ if not match:
142
+ return None
143
+ return tuple(int(x) for x in match.groups())
144
+
145
+
146
+ def parse_dep_key(key):
147
+ """
148
+ 'owner/repo' -> assumed GitHub
149
+ 'https://example.com/owner/repo.git' -> explicit git URL
150
+ 'git@example.com:owner/repo.git' -> explicit git URL (ssh)
151
+ In all cases the local install path is jq_modules/<owner>/<repo>,
152
+ derived from the last two path segments, so `import "owner/repo"`
153
+ works the same regardless of where it actually came from.
154
+ """
155
+ if "://" in key or key.startswith("git@"):
156
+ url = key
157
+ path = re.sub(r"\.git$", "", url.split(":")[-1].rstrip("/"))
158
+ parts = [p for p in path.split("/") if p]
159
+ if len(parts) < 2:
160
+ die(f"can't infer owner/repo from URL '{key}'")
161
+ owner, repo = parts[-2], parts[-1]
162
+ return owner, repo, url
163
+ if "/" not in key:
164
+ die(f"dependency key '{key}' must be 'owner/repo' or a full git URL")
165
+ owner, repo = key.split("/", 1)
166
+ return owner, repo, f"https://github.com/{owner}/{repo}.git"
167
+
168
+
169
+ def parse_spec(spec):
170
+ """Return ('exact'|'caret'|'tilde'|'latest'|'ref', value)"""
171
+ spec = (spec or "*").strip()
172
+ if spec in ("", "*", "latest"):
173
+ return ("latest", None)
174
+ if spec.startswith("#"):
175
+ return ("ref", spec[1:])
176
+ if spec.startswith("^"):
177
+ v = semver_tuple(spec[1:])
178
+ if not v:
179
+ die(f"bad version spec: {spec}")
180
+ return ("caret", v)
181
+ if spec.startswith("~"):
182
+ v = semver_tuple(spec[1:])
183
+ if not v:
184
+ die(f"bad version spec: {spec}")
185
+ return ("tilde", v)
186
+ if semver_tuple(spec):
187
+ return ("exact", spec)
188
+ # anything else: treat as an explicit git ref (branch/tag/sha)
189
+ return ("ref", spec)
190
+
191
+
192
+ def list_remote_tags(url):
193
+ result = run(["git", "ls-remote", "--tags", url], check=False)
194
+ if result.returncode != 0:
195
+ return []
196
+ tags = []
197
+ for line in result.stdout.splitlines():
198
+ parts = line.split("\t")
199
+ if len(parts) != 2:
200
+ continue
201
+ ref = parts[1]
202
+ if ref.endswith("^{}"): # dereferenced annotated tag, skip dupe
203
+ continue
204
+ if ref.startswith("refs/tags/"):
205
+ tags.append(ref[len("refs/tags/"):])
206
+ return tags
207
+
208
+
209
+ def resolve_spec(url, spec):
210
+ """Return a git ref (tag/branch/sha) to check out."""
211
+ kind, value = parse_spec(spec)
212
+
213
+ if kind == "ref":
214
+ return value
215
+
216
+ tags = list_remote_tags(url)
217
+ semver_tags = [(semver_tuple(t), t) for t in tags]
218
+ semver_tags = [(v, t) for v, t in semver_tags if v is not None]
219
+ semver_tags.sort()
220
+
221
+ if kind == "exact":
222
+ target = semver_tuple(value)
223
+ for v, t in semver_tags:
224
+ if v == target:
225
+ return t
226
+ die(f"no tag matching exact version {value} found at {url}")
227
+
228
+ if kind == "latest":
229
+ if semver_tags:
230
+ return semver_tags[-1][1]
231
+ return "HEAD" # fall back to default branch
232
+
233
+ if kind == "caret":
234
+ assert isinstance(value, tuple) and len(value) == 3
235
+ major = value[0]
236
+ candidates = [(v, t) for v, t in semver_tags if v[0] == major and v >= value]
237
+ if not candidates:
238
+ die(f"no tag satisfying ^{'.'.join(map(str, value))} found at {url}")
239
+ return sorted(candidates)[-1][1]
240
+
241
+ if kind == "tilde":
242
+ assert isinstance(value, tuple) and len(value) == 3
243
+ major, minor = value[0], value[1]
244
+ candidates = [
245
+ (v, t) for v, t in semver_tags
246
+ if v[0] == major and v[1] == minor and v >= value
247
+ ]
248
+ if not candidates:
249
+ die(f"no tag satisfying ~{'.'.join(map(str, value))} found at {url}")
250
+ return sorted(candidates)[-1][1]
251
+
252
+ die(f"unhandled spec kind: {kind}")
253
+
254
+
255
+ # --------------------------------------------------------------------------
256
+ # local (relative) imports within a package
257
+ # --------------------------------------------------------------------------
258
+
259
+ # import "./x" as X; include "./x"; -- only specs starting with ./ or ../
260
+ # are local; anything else is left alone for jq's own -L search-path lookup.
261
+ LOCAL_IMPORT_RE = re.compile(r'\b(import|include)\b(\s*)"(\.\.?/[^"]*)"')
262
+
263
+
264
+ def _resolve_local_spec(file_rel_dir, spec, prefix):
265
+ """
266
+ file_rel_dir: POSIX path of the importing file's directory, relative to
267
+ the package root ("" at the root).
268
+ spec: the quoted import/include target, e.g. "./helper" or "../x/y".
269
+ prefix: the package's fully-qualified module path, e.g. "owner/repo".
270
+ Returns the rewritten, package-manager-resolvable spec.
271
+ """
272
+ joined = posixpath.normpath(posixpath.join(file_rel_dir, spec))
273
+ if joined == ".." or joined.startswith("../"):
274
+ die(f"local import \"{spec}\" in {prefix}/{file_rel_dir or '.'} "
275
+ f"escapes the package root")
276
+ return prefix if joined == "." else f"{prefix}/{joined}"
277
+
278
+
279
+ def rewrite_local_imports(root_dir, prefix):
280
+ """
281
+ Rewrite every local (./ or ../) import/include spec found in the .jq
282
+ files under root_dir into its fully-qualified `prefix/...` form, so it
283
+ resolves the same way regardless of the consuming project's own
284
+ directory. See the "Multi-file packages" note in the module docstring.
285
+ """
286
+ root_dir = Path(root_dir)
287
+ for path in sorted(root_dir.rglob("*.jq")):
288
+ rel_dir = path.parent.relative_to(root_dir).as_posix()
289
+ if rel_dir == ".":
290
+ rel_dir = ""
291
+ text = path.read_text()
292
+
293
+ def _sub(m, rel_dir=rel_dir):
294
+ keyword, ws, spec = m.group(1), m.group(2), m.group(3)
295
+ new_spec = _resolve_local_spec(rel_dir, spec, prefix)
296
+ return f'{keyword}{ws}"{new_spec}"'
297
+
298
+ new_text = LOCAL_IMPORT_RE.sub(_sub, text)
299
+ if new_text != text:
300
+ path.write_text(new_text)
301
+
302
+
303
+ # --------------------------------------------------------------------------
304
+ # install
305
+ # --------------------------------------------------------------------------
306
+
307
+ def install_one(owner, repo, url, spec, locked_entry=None):
308
+ """Fetch one package into jq_modules/ and return its lock entry
309
+ (without the "direct"/"requested_by" bookkeeping fields, which the
310
+ caller fills in)."""
311
+ if locked_entry and locked_entry.get("source") == url and locked_entry.get("spec") == spec:
312
+ # Reproducible install: reuse the exact commit from the lockfile
313
+ # instead of re-resolving the spec against remote tags.
314
+ ref = locked_entry["commit"]
315
+ resolved = locked_entry["resolved"]
316
+ print(f" {owner}/{repo} (locked @ {ref[:8]})")
317
+ else:
318
+ ref = resolve_spec(url, spec)
319
+ resolved = ref
320
+ print(f" {owner}/{repo} ({spec} -> {ref})")
321
+
322
+ dest = Path(MODULES_DIR) / owner / repo
323
+
324
+ if dest.exists():
325
+ run(["rm", "-rf", str(dest)], capture=True)
326
+ dest.parent.mkdir(parents=True, exist_ok=True)
327
+
328
+ run(["git", "clone", "--quiet", url, str(dest)])
329
+ checkout_ref = ref if ref != "HEAD" else _default_branch(dest)
330
+ run(["git", "-C", str(dest), "checkout", "--quiet", checkout_ref])
331
+ commit = run(["git", "-C", str(dest), "rev-parse", "HEAD"]).stdout.strip()
332
+ run(["rm", "-rf", str(dest / ".git")], capture=True) # keep installed tree lean
333
+ rewrite_local_imports(dest, f"{owner}/{repo}")
334
+
335
+ entry = dest / f"{repo}.jq"
336
+ if not entry.exists():
337
+ print(f" warning: expected entry file {entry} not found. "
338
+ f"'import \"{owner}/{repo}\"' will fail unless the package "
339
+ f"provides {repo}.jq at its root.", file=sys.stderr)
340
+
341
+ return {
342
+ "source": url,
343
+ "spec": spec,
344
+ "resolved": resolved,
345
+ "commit": commit,
346
+ }
347
+
348
+
349
+ def _default_branch(dest):
350
+ result = run(["git", "-C", str(dest), "symbolic-ref", "refs/remotes/origin/HEAD"], check=False)
351
+ if result.returncode == 0:
352
+ return result.stdout.strip().split("/")[-1]
353
+ return "HEAD"
354
+
355
+
356
+ def _dep_entry(key, value):
357
+ """Turn one `dependencies` map entry (either manifest form) into
358
+ (owner, repo, url, spec)."""
359
+ if isinstance(value, dict):
360
+ owner, repo, _ = parse_dep_key(key)
361
+ url, spec = value["url"], value.get("version", "*")
362
+ else:
363
+ owner, repo, url = parse_dep_key(key)
364
+ spec = value
365
+ return owner, repo, url, spec
366
+
367
+
368
+ def _reconcile(key, url, spec, direct, existing, requested_by):
369
+ """Two different requirements were made for an already-resolved
370
+ dependency `key`. Return 'keep' (existing wins) or 'replace' (the new
371
+ request wins and must be (re)installed), or die if the conflict can't
372
+ be ordered automatically."""
373
+ if direct:
374
+ # An explicit top-level dependency always wins over anything
375
+ # merely inferred transitively.
376
+ return "replace" if not existing.get("direct") else "keep"
377
+ if existing.get("direct"):
378
+ return "keep"
379
+
380
+ if existing["source"] != url:
381
+ die(f"conflicting sources requested for {key}:\n"
382
+ f" {existing['requested_by'][-1]} wants {existing['source']}\n"
383
+ f" {requested_by} wants {url}\n"
384
+ f"Add an explicit top-level dependency on {key} in {MANIFEST} "
385
+ f"to resolve this.")
386
+
387
+ new_kind, _ = parse_spec(spec)
388
+ old_kind, _ = parse_spec(existing["spec"])
389
+ if new_kind == "ref" or old_kind == "ref":
390
+ die(f"conflicting versions requested for {key}:\n"
391
+ f" {existing['requested_by'][-1]} wants '{existing['spec']}'\n"
392
+ f" {requested_by} wants '{spec}'\n"
393
+ f"Add an explicit top-level dependency on {key} in {MANIFEST} "
394
+ f"to pin a version.")
395
+
396
+ new_ref = resolve_spec(url, spec)
397
+ new_v, old_v = semver_tuple(new_ref), semver_tuple(existing["resolved"])
398
+ if new_v is None or old_v is None:
399
+ die(f"conflicting versions requested for {key}: "
400
+ f"'{existing['spec']}' (-> {existing['resolved']}) vs "
401
+ f"'{spec}' (-> {new_ref}); neither pair resolves to a "
402
+ f"comparable semver tag. Add an explicit top-level dependency "
403
+ f"on {key} in {MANIFEST} to pin a version.")
404
+ return "replace" if new_v > old_v else "keep"
405
+
406
+
407
+ def install_dependency(owner, repo, url, spec, lock, existing_lock, direct, requested_by,
408
+ chain, recurse=True):
409
+ """Install `owner/repo` -- and, if `recurse`, walk into whatever it
410
+ (transitively) depends on via its own jqpackage.json -- flattening the
411
+ whole graph into `lock` / jq_modules/."""
412
+ key = f"{owner}/{repo}"
413
+ if key in chain:
414
+ die(f"dependency cycle detected: {' -> '.join(chain + [key])}")
415
+
416
+ existing = lock.get(key)
417
+ if existing is not None:
418
+ same_request = existing["source"] == url and existing["spec"] == spec
419
+ decision = "keep" if same_request else _reconcile(key, url, spec, direct, existing, requested_by)
420
+ existing["direct"] = existing.get("direct") or direct
421
+ if requested_by not in existing["requested_by"]:
422
+ existing["requested_by"].append(requested_by)
423
+ if decision == "keep":
424
+ return
425
+
426
+ entry = install_one(owner, repo, url, spec, locked_entry=existing_lock.get(key))
427
+ entry["direct"] = direct or (existing["direct"] if existing else False)
428
+ entry["requested_by"] = existing["requested_by"] if existing else [requested_by]
429
+ lock[key] = entry
430
+
431
+ if recurse:
432
+ install_transitive_deps(owner, repo, lock, existing_lock, chain + [key])
433
+
434
+
435
+ def install_transitive_deps(owner, repo, lock, existing_lock, chain):
436
+ """Install whatever `owner/repo`'s own jqpackage.json (if it ships one)
437
+ declares as dependencies."""
438
+ sub_manifest = load_json(Path(MODULES_DIR) / owner / repo / MANIFEST)
439
+ if not sub_manifest:
440
+ return
441
+ key = f"{owner}/{repo}"
442
+ for sub_key, sub_value in sub_manifest.get("dependencies", {}).items():
443
+ sub_owner, sub_repo, sub_url, sub_spec = _dep_entry(sub_key, sub_value)
444
+ install_dependency(
445
+ sub_owner, sub_repo, sub_url, sub_spec, lock, existing_lock,
446
+ direct=False, requested_by=key, chain=chain,
447
+ )
448
+
449
+
450
+ def cmd_install(args):
451
+ manifest = load_manifest()
452
+ deps = manifest.get("dependencies", {})
453
+ if not deps:
454
+ print("no dependencies listed in jqpackage.json")
455
+ return
456
+ existing_lock = {} if args.update else load_json(LOCKFILE, {})
457
+ lock = {}
458
+ print(f"installing dependencies into {MODULES_DIR}/ (including transitive ones)")
459
+ # Install every direct (top-level) dependency first, so an explicit
460
+ # jqpackage.json pin is always in place before any transitive request
461
+ # for the same package is seen -- regardless of manifest key order.
462
+ direct = []
463
+ for key, value in deps.items():
464
+ owner, repo, url, spec = _dep_entry(key, value)
465
+ install_dependency(owner, repo, url, spec, lock, existing_lock,
466
+ direct=True, requested_by="(project)", chain=[], recurse=False)
467
+ direct.append((owner, repo))
468
+ for owner, repo in direct:
469
+ install_transitive_deps(owner, repo, lock, existing_lock, chain=[f"{owner}/{repo}"])
470
+ save_json(LOCKFILE, lock)
471
+ print(f"done ({len(lock)} package(s) installed).")
472
+
473
+
474
+ # --------------------------------------------------------------------------
475
+ # other commands
476
+ # --------------------------------------------------------------------------
477
+
478
+ def cmd_init(args):
479
+ if Path(MANIFEST).exists() and not args.force:
480
+ die(f"{MANIFEST} already exists (use --force to overwrite)")
481
+ name = args.name or Path.cwd().name
482
+ manifest = {
483
+ "name": name,
484
+ "version": "0.1.0",
485
+ "description": "",
486
+ "main": "main.jq",
487
+ "dependencies": {},
488
+ }
489
+ save_json(MANIFEST, manifest)
490
+ print(f"created {MANIFEST}")
491
+
492
+
493
+ SSH_SCP_RE = re.compile(r"^[^@/\s]+@[^@/\s]+:")
494
+
495
+
496
+ def split_pkg_and_spec(raw):
497
+ """
498
+ 'owner/repo' -> ('owner/repo', '*')
499
+ 'owner/repo@^1.0.0' -> ('owner/repo', '^1.0.0')
500
+ 'https://host/o/r.git' -> ('https://host/o/r.git', '*')
501
+ 'https://host/o/r.git@^1.0.0' -> ('https://host/o/r.git', '^1.0.0')
502
+ 'git@host:o/r.git' -> ('git@host:o/r.git', '*')
503
+ 'git@host:o/r.git@^1.0.0' -> ('git@host:o/r.git', '^1.0.0')
504
+ A URL's own '://' is protected from being mistaken for the '@' split
505
+ by only splitting on the LAST '@'. An scp-like ssh URL ('user@host:path')
506
+ has its own leading '@' that is never a version separator, so that
507
+ prefix is stripped first and the version split only applies after it.
508
+ """
509
+ match = SSH_SCP_RE.match(raw)
510
+ if match:
511
+ prefix, rest = raw[:match.end()], raw[match.end():]
512
+ if "@" in rest:
513
+ path, spec = rest.rsplit("@", 1)
514
+ return prefix + path, spec
515
+ return raw, "*"
516
+ if "@" in raw:
517
+ head, spec = raw.rsplit("@", 1)
518
+ if head == "" or head.endswith(":"):
519
+ return raw, "*"
520
+ return head, spec
521
+ return raw, "*"
522
+
523
+
524
+ def cmd_add(args):
525
+ manifest = load_manifest()
526
+ for raw in args.packages:
527
+ key, spec = split_pkg_and_spec(raw)
528
+ owner, repo, url = parse_dep_key(key)
529
+ dep_key = f"{owner}/{repo}"
530
+ is_default_github = url == f"https://github.com/{owner}/{repo}.git"
531
+ if is_default_github:
532
+ manifest["dependencies"][dep_key] = spec
533
+ else:
534
+ manifest["dependencies"][dep_key] = {"url": url, "version": spec}
535
+ save_json(MANIFEST, manifest)
536
+ print(f"added to {MANIFEST}, run `jqpm install` to fetch")
537
+ if args.install:
538
+ cmd_install(argparse.Namespace(update=False))
539
+
540
+
541
+ def cmd_remove(args):
542
+ manifest = load_manifest()
543
+ lock = load_json(LOCKFILE, {})
544
+ for key in args.packages:
545
+ owner, repo, _ = parse_dep_key(key)
546
+ full = f"{owner}/{repo}"
547
+ manifest["dependencies"].pop(full, None)
548
+ lock.pop(full, None)
549
+ dest = Path(MODULES_DIR) / owner / repo
550
+ if dest.exists():
551
+ run(["rm", "-rf", str(dest)])
552
+ print(f"removed {full}")
553
+ save_json(MANIFEST, manifest)
554
+ save_json(LOCKFILE, lock)
555
+
556
+
557
+ def cmd_list(args):
558
+ lock = load_json(LOCKFILE, {})
559
+ if not lock:
560
+ print("no packages installed (run `jqpm install`)")
561
+ return
562
+ for key, info in lock.items():
563
+ via = ""
564
+ if not info.get("direct", True):
565
+ via = f" (transitive, via {', '.join(info.get('requested_by', []))})"
566
+ print(f"{key} {info['spec']} -> {info['resolved']} ({info['commit'][:8]}){via}")
567
+
568
+
569
+ def cmd_run(args):
570
+ modules_path = str(Path(MODULES_DIR).resolve())
571
+ jq_args = args.jq_args
572
+ if jq_args and jq_args[0] == "--":
573
+ jq_args = jq_args[1:]
574
+ cmd = ["jq", "-L", modules_path] + jq_args
575
+ os.execvp("jq", cmd)
576
+
577
+
578
+ # --------------------------------------------------------------------------
579
+ # CLI
580
+ # --------------------------------------------------------------------------
581
+
582
+ def main():
583
+ parser = argparse.ArgumentParser(prog="jqpm", description="A minimal package manager for jq")
584
+ parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
585
+ sub = parser.add_subparsers(dest="command", required=True)
586
+
587
+ p = sub.add_parser("init", help="create a jqpackage.json in the current directory")
588
+ p.add_argument("--name")
589
+ p.add_argument("--force", action="store_true")
590
+ p.set_defaults(func=cmd_init)
591
+
592
+ p = sub.add_parser("install", help="install all dependencies from jqpackage.json")
593
+ p.add_argument("--update", action="store_true", help="re-resolve versions, ignoring the lockfile")
594
+ p.set_defaults(func=cmd_install)
595
+
596
+ p = sub.add_parser("add", help="add package(s) to jqpackage.json, e.g. `jqpm add owner/repo@^1.0.0`")
597
+ p.add_argument("packages", nargs="+")
598
+ p.add_argument("--no-install", dest="install", action="store_false", default=True)
599
+ p.set_defaults(func=cmd_add)
600
+
601
+ p = sub.add_parser("remove", help="remove package(s)")
602
+ p.add_argument("packages", nargs="+")
603
+ p.set_defaults(func=cmd_remove)
604
+
605
+ p = sub.add_parser("list", help="list installed packages")
606
+ p.set_defaults(func=cmd_list)
607
+
608
+ p = sub.add_parser("run", help="run jq with -L jq_modules already set, e.g. `jqpm run -- 'import ...'`")
609
+ p.add_argument("jq_args", nargs=argparse.REMAINDER)
610
+ p.set_defaults(func=cmd_run)
611
+
612
+ args = parser.parse_args()
613
+ args.func(args)
614
+
615
+
616
+ if __name__ == "__main__":
617
+ main()