=== BEGIN ARTIFACT ARCHITECTURE.md ===
# ARCHITECTURE: jq Interpreter
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Defines the modular standard-library Python architecture for the standalone jq interpreter. |
| Depends On | — |
| Provides | interpreter module boundaries, executable boundary |
| Consumes | — |
## Questions
- None.
## Intent
The interpreter is a standalone executable named `jq`. It accepts `./jq -c '<program>'`, reads JSON values from standard input, evaluates jq filters as ordered generators, and writes compact JSON values to standard output.
## Technology Stack
- Python 3.11 or newer, using only the standard library.
- POSIX `sh` for the supplied scoring entry point.
- No third-party runtime dependency, network access, package installation, jq binding, or shell-out to another jq executable.
## Modules and Boundaries
| Boundary | Responsibility |
|---|---|
| `jq` executable | Parse command-line arguments, read standard input, invoke the interpreter, serialize outputs, and map failures to exit codes. |
| Lexer | Tokenize jq literals, identifiers, fields, bindings, keywords, operators, delimiters, comments, formats, and interpolated strings. |
| Parser | Produce an AST or equivalent intermediate representation, enforce precedence and static validity, and reject invalid programs. |
| Evaluator | Execute filters as ordered streams, preserving multiplicity, backtracking, Cartesian products, and partial output. |
| Runtime values | Represent JSON values, literal-aware numbers, NaN, infinities, arrays, objects, and immutable transformations. |
| Builtins | Implement jq primitives and standard-library filters over the evaluator's stream model. |
| Paths and assignment | Discover paths and apply immutable reads, writes, updates, and deletions. |
| Diagnostics | Keep compile failures, runtime failures, stderr output, and successful completion distinct. |
The executable boundary must not depend on a system jq command or an external implementation. Parser and evaluator interfaces remain internal to the Python implementation; the only public interface is the executable process contract.
## Runtime Contracts
- Compile failure exits `3`.
- Runtime failure exits `5`.
- Successful completion exits `0`.
- Diagnostics are written to stderr.
- Each produced value is serialized as one compact JSON value per line.
- Values emitted before a runtime failure remain on stdout.
- Generator ordering and multiplicity are observable and must be preserved.
## Module Ownership
| Concern | Owning boundary | Allowed dependencies |
|---|---|---|
| Process and CLI | executable boundary | parser, evaluator, serializer, diagnostics |
| Syntax | lexer and parser | standard-library text handling, AST definitions |
| Evaluation | evaluator | AST, runtime values, builtins, paths |
| Persistence/configuration | none | jq has no persistent store or application configuration |
| File store | none | module loading is excluded by the fixed interface |
| External services | none | network and external runtimes are forbidden |
## Numeric Decision
Use a literal-aware standard-library numeric model. Preserve source/input number spelling where jq semantics require it, perform arithmetic using standard-library numeric operations, and support special floating-point values without adding dependencies.
## Source Role Context
The implementation uses the staged lexer, parser, manual, builtin reference, corpus, and conformance harness as read-only context. The staged harness remains external to the implementation and is never modified.
## Programmatic Acceptance
- None. This specification defines architecture and boundaries; executable behavior is verified by the implementing feature specifications and the terminal conformance story.
## User Acceptance
- None.
## Guardrails
- Do not add third-party dependencies.
- Do not modify files under `sources/`.
- Do not shell out to a system jq executable.
- Do not collapse generator streams into single return values.
- Do not conflate compile exit `3` with runtime exit `5`.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Executable-Entry-Point.md ===
# FEATURE: Executable jq Entry Point
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Provides the executable jq command and its basic stdin-to-stdout filter interface. |
| Depends On | ARCHITECTURE.md |
| Provides | ./jq -c program execution |
| Consumes | interpreter parser and evaluator |
## Questions
- None.
## Workflow
1. Start the executable at the application root as `./jq`.
2. Accept the exercised `-c '<program>'` interface.
3. Read JSON input from standard input.
4. Compile and evaluate the jq program for each input value.
5. Emit each generated result as one compact JSON line.
6. Exit successfully after all inputs complete.
The implementation must support multiple input values and preserve output order. The executable may delegate to modular Python files beside it, but the delivered command remains the root-level executable named `jq`.
## Interface
| Input | Contract |
|---|---|
| Arguments | `-c` followed by one jq program string. |
| Standard input | JSON values in the corpus input format. |
| Standard output | One compact JSON value per generated result line. |
| Standard error | Diagnostics only. |
| Success status | `0`. |
## Programmatic Acceptance
=== AC exec-001-conformance ===
Intent: The executable runs the non-empty corpus slice selected for the basic executable interface and produces a clean scoped conformance result.
import json
import os
import subprocess
import sys
selector = r"^(true|false|null|1)$"
result = subprocess.run(
[sys.executable, "sources/run_conformance.py", "--select", selector, "--json"],
capture_output=True,
text=True,
env={**os.environ, "JQ": f"{os.getcwd()}/jq"},
)
print(result.stdout)
print(result.stderr, file=sys.stderr)
report = json.loads(result.stdout)
summary = report["summary"]
assert sum(summary.values()) > 0
assert summary["fail"] == 0
assert summary["error"] == 0
assert result.returncode == 0
=== END AC exec-001-conformance ===
=== AC exec-001-process ===
Intent: The executable accepts the declared -c interface and completes a supplied identity filter successfully.
import json
import subprocess
payload = "null\n"
result = subprocess.run(
["./jq", "-c", "."],
input=payload,
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr, file=__import__("sys").stderr)
assert result.returncode == 0
assert result.stdout.splitlines() == [payload.strip()]
=== END AC exec-001-process ===
## User Acceptance
- None.
## Guardrails
- The delivered command is exactly `jq` at the application root.
- The implementation accepts the exercised `-c` interface.
- Output is compact and line-oriented.
- The executable does not invoke another jq implementation.
- Diagnostics are not written to standard output.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Process-Contract.md ===
# FEATURE: jq Process Contract
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Defines jq compilation, runtime failure, success, partial-output, and diagnostic process behavior. |
| Depends On | FEATURE-Executable-Entry-Point.md |
| Provides | compile exit 3, runtime exit 5, success exit 0, stderr diagnostics |
| Consumes | ./jq -c program execution |
## Questions
- None.
## Compile and Runtime Outcomes
| Condition | Exit |
|---|---:|
| Program compiles and finishes | `0` |
| Program is rejected during compilation | `3` |
| Program compiles and raises during evaluation | `5` |
A compile failure must not be reported as a runtime failure. A runtime failure may occur after values have already been emitted; those values remain observable on stdout. Diagnostics go to stderr and are not part of the value stream.
## Programmatic Acceptance
=== AC exec-002-compile-runtime ===
Intent: The supplied conformance runner executes a non-empty slice containing compile and runtime contract cases and reports no failures or errors.
import json
import os
import subprocess
import sys
selector = r"%%FAIL|try |error|\?"
result = subprocess.run(
[sys.executable, "sources/run_conformance.py", "--select", selector, "--json"],
capture_output=True,
text=True,
env={**os.environ, "JQ": f"{os.getcwd()}/jq"},
)
print(result.stdout)
print(result.stderr, file=sys.stderr)
report = json.loads(result.stdout)
summary = report["summary"]
assert sum(summary.values()) > 0
assert summary["fail"] == 0
assert summary["error"] == 0
assert result.returncode == 0
=== END AC exec-002-compile-runtime ===
=== AC exec-002-statuses ===
Intent: The executable exposes distinct compile, runtime, and successful completion statuses.
import subprocess
compile_result = subprocess.run(
["./jq", "-c", "{",],
input="null\n",
capture_output=True,
text=True,
)
runtime_result = subprocess.run(
["./jq", "-c", "error"],
input="null\n",
capture_output=True,
text=True,
)
success_result = subprocess.run(
["./jq", "-c", "."],
input="null\n",
capture_output=True,
text=True,
)
assert compile_result.returncode == 3
assert runtime_result.returncode == 5
assert success_result.returncode == 0
=== END AC exec-002-statuses ===
=== AC exec-002-partial-output ===
Intent: A runtime failure preserves values emitted before the failure and keeps diagnostics off standard output.
import subprocess
result = subprocess.run(
["./jq", "-c", "1, error"],
input="null\n",
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr, file=__import__("sys").stderr)
assert result.returncode == 5
assert result.stdout.splitlines() == ["1"]
assert result.stderr != ""
=== END AC exec-002-partial-output ===
## User Acceptance
- None.
## Guardrails
- Compile failures exit `3`.
- Runtime failures exit `5`.
- Successful completion exits `0`.
- Runtime output produced before failure is preserved.
- Diagnostics are written to stderr only.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Json-IO.md ===
# FEATURE: JSON Input and Output
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Provides ordered JSON input processing, Unicode handling, numeric values, and compact output serialization. |
| Depends On | FEATURE-Process-Contract.md |
| Provides | JSON stdin parsing, compact JSON serialization, ordered output stream |
| Consumes | ./jq -c program execution |
## Questions
- None.
## Input Processing
Read the JSON values supplied by standard input in corpus order. Evaluate the filter independently against each input while preserving the global output order. Support Unicode escapes and characters, embedded control characters, large numeric literals, NaN, and infinities where required by jq semantics.
## Output Processing
Serialize every generated jq value as one compact JSON value per line. Structural comparison, not object key spelling or whitespace, defines conformance, but serialization must remain valid JSON-compatible output for the harness. Preserve generator multiplicity and ordering.
## Programmatic Acceptance
=== AC exec-003-conformance ===
Intent: The supplied conformance runner executes a non-empty slice covering JSON conversion, special numbers, Unicode, and output behavior with no failed or errored cases.
import json
import os
import subprocess
import sys
selector = r"nan|infinite|tojson|fromjson|@base64|@uri"
result = subprocess.run(
[sys.executable, "sources/run_conformance.py", "--select", selector, "--json"],
capture_output=True,
text=True,
env={**os.environ, "JQ": f"{os.getcwd()}/jq"},
)
print(result.stdout)
print(result.stderr, file=sys.stderr)
report = json.loads(result.stdout)
summary = report["summary"]
assert sum(summary.values()) > 0
assert summary["fail"] == 0
assert summary["error"] == 0
assert result.returncode == 0
=== END AC exec-003-conformance ===
=== AC exec-003-multiple-inputs ===
Intent: Multiple newline-delimited JSON inputs produce outputs in input and generator order.
import subprocess
inputs = "1\n2\n3\n"
result = subprocess.run(
["./jq", "-c", "."],
input=inputs,
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr, file=__import__("sys").stderr)
assert result.returncode == 0
assert result.stdout.splitlines() == inputs.splitlines()
=== END AC exec-003-multiple-inputs ===
=== AC exec-003-unicode-and-compact ===
Intent: Unicode input is decoded and emitted as one compact JSON value per line.
import subprocess
value = '"\\u03bc"'
result = subprocess.run(
["./jq", "-c", "."],
input=value + "\n",
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr, file=__import__("sys").stderr)
assert result.returncode == 0
lines = result.stdout.splitlines()
assert len(lines) == 1
assert __import__("json").loads(lines[0]) == __import__("json").loads(value)
=== END AC exec-003-unicode-and-compact ===
## User Acceptance
- None.
## Guardrails
- Preserve input and output ordering.
- Emit one output value per line.
- Do not pretty-print output.
- Preserve generator multiplicity.
- Do not silently discard Unicode or special numeric values required by the corpus.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Lexer.md ===
# FEATURE: jq Lexer
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Tokenizes jq source text into the lexical forms required by the parser and evaluator. |
| Depends On | ARCHITECTURE.md, FEATURE-Json-IO.md |
| Provides | jq tokenization |
| Consumes | interpreter executable boundary |
## Questions
- None.
## Lexical Scope
Implement lexical recognition for:
- JSON literals and numeric forms, including exponent notation.
- Identifiers, field names, variable bindings, and qualified names.
- jq keywords such as `def`, `if`, `reduce`, `try`, `label`, `module`, and `include`.
- Operators including arithmetic, comparison, pipe, comma, alternative, assignment, and optional forms.
- Parentheses, brackets, braces, separators, and delimiters.
- Line comments beginning with `#`, including the source-defined continuation behavior.
- Format tokens beginning with `@`.
- Quoted strings, JSON escapes, and interpolation markers.
The lexer must reject invalid characters and malformed escapes so the parser can report a compile failure with exit code `3`.
## Source Contract
`sources/lexer.l` is the lexical authority. `sources/parser.y` consumes the corresponding token categories. The lexer must not load module files or introduce command-line behavior beyond the fixed `-c` interface.
## Programmatic Acceptance
=== AC parse-001-conformance ===
Intent: The supplied conformance runner executes a non-empty lexical slice and reports no failed or errored cases.
import json
import os
import subprocess
import sys
selector = r"^(true|false|null|1|\.)$"
result = subprocess.run(
[sys.executable, "sources/run_conformance.py", "--select", selector, "--json"],
capture_output=True,
text=True,
env={**os.environ, "JQ": f"{os.getcwd()}/jq"},
)
print(result.stdout)
print(result.stderr, file=sys.stderr)
report = json.loads(result.stdout)
summary = report["summary"]
assert sum(summary.values()) > 0
assert summary["fail"] == 0
assert summary["error"] == 0
assert result.returncode == 0
=== END AC parse-001-conformance ===
=== AC parse-001-comments-and-keywords ===
Intent: Lexical comments and keyword identifiers remain distinguishable in valid jq source.
import json
import subprocess
program = "{if:0,and:1,or:2,then:3,else:4,elif:5,end:6,as:7,def:8}"
result = subprocess.run(
["./jq", "-c", program],
input="null\n",
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr, file=__import__("sys").stderr)
assert result.returncode == 0
actual = json.loads(result.stdout)
assert actual == {
"if": 0,
"and": 1,
"or": 2,
"then": 3,
"else": 4,
"elif": 5,
"end": 6,
"as": 7,
"def": 8,
}
=== END AC parse-001-comments-and-keywords ===
=== AC parse-001-invalid-lexeme ===
Intent: An invalid escape is rejected during compilation with the declared compile-failure status.
import subprocess
result = subprocess.run(
["./jq", "-c", '"u\\vw"'],
input="null\n",
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr, file=__import__("sys").stderr)
assert result.returncode == 3
=== END AC parse-001-invalid-lexeme ===
## User Acceptance
- None.
## Guardrails
- Follow the token categories and delimiter-state behavior defined by `sources/lexer.l`.
- Preserve string escape and interpolation markers for parser consumption.
- Reject malformed escapes and invalid characters at compile time.
- Keep comments out of the token stream.
- Do not modify staged lexical or parser sources.
=== END ARTIFACT ===Run artifact