Metadata-Version: 2.4
Name: modash
Version: 0.5.0
Summary: Merge Bash script projects into a single output file
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/nmehran/modash
Project-URL: Source, https://github.com/nmehran/modash
Project-URL: Issues, https://github.com/nmehran/modash/issues
Project-URL: Changelog, https://github.com/nmehran/modash/blob/master/CHANGELOG.md
Keywords: bash,shell,source,compiler,dependency-resolution
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Shells
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# modash

`modash` merges Bash script projects into one file.

It resolves `source` dependencies without executing shell code during normal
compile. When a source path is genuinely runtime-dependent, `modash` also
provides an explicit observe -> review -> supplement workflow.

## Install

```sh
python -m pip install modash
```

For source-tree development:

```sh
git clone https://github.com/nmehran/modash.git
cd modash
python -m pip install -e .
```

No external runtime dependencies are required.

## Quick Start

Readable review output:

```sh
modash scripts/main.sh merged-context.sh
```

Runnable output for the supported Bash subset:

```sh
modash scripts/main.sh merged.sh --mode executable
```

If executable mode cannot prove a `source` site is safe to lower, it fails
before writing or overwriting the output file.

## Output Modes

### Context Mode

Context mode is the default. It writes dependency-first sections for the files
`modash` can resolve, preserves original source lines, and annotates resolved
relationships:

```bash
# modash: source ./dep.sh -> dep.sh
source ./dep.sh
```

Use context mode for review, debugging, and collecting complete shell-project
context for another tool. It is not a runtime parity mode.

### Executable Mode

Executable mode inlines sourced files at their source sites so supported parent
shell state remains Bash-equivalent: variables, functions, `set` state, current
directory, source arguments, repeated sources, and function-scoped sources.

The supported static subset includes exact paths, exact variables, safe path
commands and file producers, arrays, finite loops, modeled read loops,
branch-aware `if` and `case` source sites, child-shell source contexts, and
bounded source-bearing function calls.

See [Supported Source Resolution](docs/supported-source-resolution.md) for the
current support matrix and fail-closed boundaries.

## Runtime Observations

Runtime tracing is explicit because it runs the target script.

```sh
modash trace scripts/main.sh --output observation.json -- --flag
modash graph scripts/main.sh --from-observation observation.json --output runtime-graph.json
modash supplement scripts/main.sh --from-graph runtime-graph.json --output source-supplement.json
modash scripts/main.sh merged.sh --mode executable --source-supplement source-supplement.json
```

After reviewing a trusted graph, the compile step can self-supplement without
writing the intermediate supplement file:

```sh
modash compile-observed scripts/main.sh merged.sh --from-graph runtime-graph.json
```

`modash trace` writes an observation JSON artifact. Current observations include
process provenance, resolved source events, linked source identities, sanitized
xtrace source provenance, schema `6` run metadata, recorded environment overlay
key names, and file fingerprints for stale-observation detection.

`modash graph` validates a trace observation and writes a trusted runtime source
graph. Graph edges link wrapper-observed source events to sanitized xtrace
provenance and fail closed if that trust link is missing, stale, or inconsistent
with the graph's process, file, edge, source identity, and fingerprint
invariants. Stale diagnostics name the file role and expected/current
fingerprint fields. It also writes a compact text review report beside the graph
by default.

`modash supplement` writes:

- a schema `1` JSON source supplement candidate
- an observation review report, defaulting to `OUTPUT.report.json`

Generated supplements are exact data, not shell code. Review the graph,
supplement, and report before compiling with `--source-supplement`.
Generation covers finite observed helper shapes, including quoted `$@` sources
and helper-local first-argument aliases such as:
`local path=$1; shift; source "$path" "$@"`.
Observation reports can warn about unobserved source-capable sites, but one
traced run is not proof of every branch.

Runtime discovery still feeds deterministic compilation through an explicit
trusted graph artifact. For automation, `observe-compile` is an explicit
one-shot command that runs the target, writes the observation, trusted graph,
and review report artifacts, then compiles from that newly observed graph.
Normal compile never traces.

## Commands

```sh
modash <entrypoint> <output> [--mode context|executable] [--source-supplement FILE]
modash trace <entrypoint> [--cwd DIR] [--env KEY=VALUE] [--output FILE] [--timeout SECONDS] [--] [args...]
modash graph <entrypoint> --from-observation observation.json --output runtime-graph.json [--report graph-review.txt]
modash supplement <entrypoint> (--from-observation observation.json [--report report.json] | --from-graph runtime-graph.json) --output source-supplement.json
modash compile-observed <entrypoint> <output> --from-graph runtime-graph.json
modash observe-compile <entrypoint> <output> --reviewed-graph-out runtime-graph.json [--observation-out observation.json] [--report graph-review.txt] [--cwd DIR] [--env KEY=VALUE] [--timeout SECONDS] [--] [args...]
```

Useful options:

- `--mode executable`: write runnable output for the supported subset.
- `--source-supplement FILE`: provide exact values for runtime-dynamic source
  sites.
- `trace --cwd DIR`: run the target script from a specific directory.
- `trace --env KEY=VALUE`: add an environment overlay for the traced run.
- `trace --timeout SECONDS`: bound target execution. Default: `30`.
- `graph --from-observation FILE`: build a trusted source graph from a trace
  observation.
- `graph --report FILE`: choose the human-readable graph review report path.
- `compile-observed --from-graph FILE`: compile executable output using a
  trusted graph and an in-memory generated supplement.
- `observe-compile --reviewed-graph-out FILE`: explicitly run tracing, write
  review artifacts, and compile executable output from the newly observed graph.
- `supplement --report FILE`: choose the review report path.

## Development

Run the local verification suite:

```sh
python -m unittest
python -m py_compile modash.py methods/*.py methods/regex/*.py test/*.py
git diff --check
```

Optional packaging checks:

```sh
python -m build --sdist --wheel --outdir dist
python -m twine check dist/*
```

Design notes live in [docs](docs/README.md).

## License

This project is licensed under the Apache 2.0 License. See [LICENSE](LICENSE).
