bc-lantern 0.7.0__tar.gz

bc_lantern-0.7.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

bc_lantern-0.7.0/.github/workflows/release.yml

@@ -0,0 +1,78 @@
+name: Release to PyPI
+
+on:
+    push:
+        tags:
+            - "v*"
+
+permissions:
+    contents: read
+
+jobs:
+    build:
+        name: Test and build distributions
+        runs-on: ubuntu-latest
+
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                  python-version: "3.13"
+                  cache: pip
+            - name: Install development tools
+              run: python -m pip install ".[dev]"
+            - name: Verify tag matches package version
+              shell: python
+              run: |
+                  import os
+                  import pathlib
+                  import tomllib
+
+                  tag_version = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+                  project = tomllib.loads(
+                      pathlib.Path("pyproject.toml").read_text(encoding="utf-8")
+                  )["project"]
+                  if project["version"] != tag_version:
+                      raise SystemExit(
+                          f"Tag version {tag_version!r} does not match "
+                          f"project version {project['version']!r}"
+                      )
+            - run: python -m pytest
+            - run: bcl docs sync --check
+            - name: Build distributions
+              run: python -m build
+            - name: Check distribution metadata
+              run: python -m twine check dist/*
+            - name: Test the built wheel
+              run: |
+                  python -m venv /tmp/bc-lantern-wheel
+                  /tmp/bc-lantern-wheel/bin/python -m pip install dist/*.whl
+                  /tmp/bc-lantern-wheel/bin/bcl --help
+            - name: Test the source distribution
+              run: |
+                  python -m venv /tmp/bc-lantern-sdist
+                  /tmp/bc-lantern-sdist/bin/python -m pip install dist/*.tar.gz
+                  /tmp/bc-lantern-sdist/bin/bcl --help
+            - uses: actions/upload-artifact@v4
+              with:
+                  name: python-package-distributions
+                  path: dist/
+                  if-no-files-found: error
+
+    publish:
+        name: Publish distributions
+        needs: build
+        runs-on: ubuntu-latest
+        environment:
+            name: pypi
+            url: https://pypi.org/project/bc-lantern/
+        permissions:
+            id-token: write
+
+        steps:
+            - uses: actions/download-artifact@v4
+              with:
+                  name: python-package-distributions
+                  path: dist/
+            - name: Publish distributions to PyPI
+              uses: pypa/gh-action-pypi-publish@v1.14.2

bc_lantern-0.7.0/.github/workflows/tests.yml

@@ -0,0 +1,26 @@
+name: Tests
+
+on:
+    push:
+    pull_request:
+
+permissions:
+    contents: read
+
+jobs:
+    test:
+        strategy:
+            matrix:
+                os: [ubuntu-latest, windows-latest]
+                python-version: ["3.10", "3.13"]
+        runs-on: ${{ matrix.os }}
+
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                  python-version: ${{ matrix.python-version }}
+                  cache: pip
+            - run: python -m pip install -e ".[dev]"
+            - run: python -m pytest
+            - run: bcl docs sync --check

bc_lantern-0.7.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+.pytest_cache/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+app-json.json
+object-range-report*.json
+object-range-report*.md
+.smoke-output/

bc_lantern-0.7.0/CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing
+
+Contributions are welcome through GitHub issues and pull requests.
+
+## Development
+
+1. Fork and clone the repository.
+2. Create a focused branch.
+3. Install the project with `python -m pip install -e ".[dev]"`.
+4. Make the change and add or update tests.
+5. Run `python -m pytest` and `bcl docs sync --check`.
+6. Open a pull request that explains the behavior change.
+
+Keep generated aggregate and report files out of commits. By submitting a
+contribution, you agree that it is licensed under this repository's MIT License.

bc_lantern-0.7.0/LICENSE

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

bc_lantern-0.7.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.5
+Name: bc-lantern
+Version: 0.7.0
+Summary: A growing toolbox for Business Central and AL projects
+Project-URL: Homepage, https://github.com/SchulzOli/bc-lantern
+Project-URL: Documentation, https://github.com/SchulzOli/bc-lantern#readme
+Project-URL: Issues, https://github.com/SchulzOli/bc-lantern/issues
+Project-URL: Source, https://github.com/SchulzOli/bc-lantern
+Author: Oliver Schulz
+License-Expression: MIT
+License-File: LICENSE
+Keywords: al,business-central,cli,github
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# BC Lantern
+
+BC Lantern is a Python command-line toolbox for Microsoft Dynamics 365 Business Central
+and AL projects.
+
+It can:
+
+- collect `app.json` manifests from GitHub repositories that contain AL code;
+- cache manifests and download only changed files;
+- compare declared object ranges with a central allocation file;
+- report reservations, free ranges, conflicts, and ranges outside the allocation;
+- write object-range reports as JSON or Markdown.
+
+## Requirements
+
+- Python 3.10 or later
+- [GitHub CLI](https://cli.github.com/) for `app-json retrieve`
+- Git for installation directly from GitHub
+
+Authenticate GitHub CLI before you collect manifests:
+
+```text
+gh auth login
+```
+
+The authenticated account controls access to private repositories.
+
+## Install
+
+### Install from PyPI
+
+Use `pipx` to install BC Lantern in an isolated environment:
+
+```text
+pipx install bc-lantern
+```
+
+You can also use pip:
+
+```text
+python -m pip install bc-lantern
+```
+
+Upgrade an existing installation:
+
+```text
+pipx upgrade bc-lantern
+```
+
+### Install from GitHub
+
+Install a specific release tag before or without a PyPI release:
+
+```text
+python -m pip install "bc-lantern @ git+https://github.com/SchulzOli/bc-lantern.git@v0.7.0"
+```
+
+Use a tag or full commit SHA in automated builds. Do not install from `main` in
+a reproducible pipeline.
+
+Verify the installation:
+
+```text
+bcl --help
+```
+
+## Quick start
+
+### 1. Collect `app.json` manifests
+
+Collect manifests from the repositories of the authenticated GitHub account:
+
+```text
+bcl app-json retrieve
+```
+
+Collect manifests from a specified user or organization:
+
+```text
+bcl app-json retrieve \
+  --owner my-organization \
+  --output app-json.json
+```
+
+BC Lantern excludes archived repositories by default. Add `--include-archived` to
+include them.
+
+The command writes one aggregate JSON file. It does not create repository
+folders or separate manifest files.
+
+### 2. Create an allocation file
+
+Create an `object_ranges.json` file with named allocations:
+
+```json
+{
+  "My team": {
+    "ranges": [
+      { "from": 1000000, "to": 1000999 }
+    ]
+  }
+}
+```
+
+Allocation ranges are inclusive. Reference allocations must not overlap.
+
+### 3. Create an object-range report
+
+Compare the collected manifests with the allocation file:
+
+```text
+bcl object-ranges report \
+  --app-json app-json.json \
+  --reference object_ranges.json \
+  --output object-range-report.json
+```
+
+Create a Markdown report:
+
+```text
+bcl object-ranges report \
+  --reference object_ranges.json \
+  --output object-range-report.md \
+  --output-format markdown
+```
+
+`--app-json` defaults to `app-json.json`. The JSON output defaults to
+`object-range-report.json`.
+
+The report compares declared reservations. It does not scan AL source files for
+implemented object IDs.
+
+## Range filters
+
+BC Lantern classifies declared ranges with these Business Central categories:
+
+| Type | Inclusive IDs |
+|---|---:|
+| `base` | 0-49,999 |
+| `customization` | 50,000-99,999 |
+| `localization` | 100,000-999,999 |
+| `rsp` | 1,000,000-69,999,999 |
+| `app` | 70,000,000-74,999,999 |
+| `unclassified` | 75,000,000 and above |
+
+Hide a category from report details but keep it in calculations:
+
+```text
+bcl object-ranges report \
+  --reference object_ranges.json \
+  --hide-range-type rsp
+```
+
+Remove a category from all calculations:
+
+```text
+bcl object-ranges report \
+  --reference object_ranges.json \
+  --ignore-range-type customization
+```
+
+Both options are repeatable. Use `--conflict-range-type` to replace the default
+set of conflict-enabled categories. By default, all categories except
+`customization` participate in conflict detection.
+
+See the [CLI reference](docs/cli-reference.md) for every command and option.
+
+## Cache
+
+BC Lantern caches GitHub metadata and manifests by default:
+
+```text
+Windows: %LOCALAPPDATA%\bc-lantern\cache
+macOS:   ~/Library/Caches/bc-lantern
+Linux:   ${XDG_CACHE_HOME:-~/.cache}/bc-lantern
+```
+
+Force a complete scan:
+
+```text
+bcl app-json retrieve --refresh
+```
+
+Disable the cache:
+
+```text
+bcl app-json retrieve --no-cache
+```
+
+Set another cache directory:
+
+```text
+bcl app-json retrieve --cache-dir path/to/cache
+```
+
+## Pipeline example
+
+Pin the package version in a pipeline:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+
+  - uses: actions/setup-python@v5
+    with:
+      python-version: "3.13"
+
+  - run: python -m pip install bc-lantern==0.7.0
+
+  - run: >-
+      bcl object-ranges report
+      --app-json app-json.json
+      --reference object_ranges.json
+      --output object-range-report.json
+```
+
+The pipeline must provide `app-json.json` and `object_ranges.json`. Alternatively,
+run `app-json retrieve` first and authenticate GitHub CLI in the pipeline.
+
+## PowerShell example
+
+[`example.ps1`](example.ps1) collects manifests and creates several reports:
+
+```powershell
+.\example.ps1 `
+  -Owner my-organization `
+  -Reference C:\path\to\object_ranges.json
+```
+
+Generated aggregates and reports are ignored by Git. They can contain repository
+metadata.
+
+## Development
+
+Install the project and its development tools:
+
+```text
+python -m pip install -e ".[dev]"
+```
+
+Run the tests:
+
+```text
+python -m pytest
+```
+
+Check the generated CLI reference:
+
+```text
+bcl docs sync --check
+```
+
+Use `bcl docs sync` after you change a command or option.
+
+## Project information
+
+- [CLI reference](docs/cli-reference.md)
+- [Contributing guide](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+- [PyPI publishing guide](docs/publishing.md)
+- [MIT License](LICENSE)

bc_lantern-0.7.0/README.md

@@ -0,0 +1,261 @@
+# BC Lantern
+
+BC Lantern is a Python command-line toolbox for Microsoft Dynamics 365 Business Central
+and AL projects.
+
+It can:
+
+- collect `app.json` manifests from GitHub repositories that contain AL code;
+- cache manifests and download only changed files;
+- compare declared object ranges with a central allocation file;
+- report reservations, free ranges, conflicts, and ranges outside the allocation;
+- write object-range reports as JSON or Markdown.
+
+## Requirements
+
+- Python 3.10 or later
+- [GitHub CLI](https://cli.github.com/) for `app-json retrieve`
+- Git for installation directly from GitHub
+
+Authenticate GitHub CLI before you collect manifests:
+
+```text
+gh auth login
+```
+
+The authenticated account controls access to private repositories.
+
+## Install
+
+### Install from PyPI
+
+Use `pipx` to install BC Lantern in an isolated environment:
+
+```text
+pipx install bc-lantern
+```
+
+You can also use pip:
+
+```text
+python -m pip install bc-lantern
+```
+
+Upgrade an existing installation:
+
+```text
+pipx upgrade bc-lantern
+```
+
+### Install from GitHub
+
+Install a specific release tag before or without a PyPI release:
+
+```text
+python -m pip install "bc-lantern @ git+https://github.com/SchulzOli/bc-lantern.git@v0.7.0"
+```
+
+Use a tag or full commit SHA in automated builds. Do not install from `main` in
+a reproducible pipeline.
+
+Verify the installation:
+
+```text
+bcl --help
+```
+
+## Quick start
+
+### 1. Collect `app.json` manifests
+
+Collect manifests from the repositories of the authenticated GitHub account:
+
+```text
+bcl app-json retrieve
+```
+
+Collect manifests from a specified user or organization:
+
+```text
+bcl app-json retrieve \
+  --owner my-organization \
+  --output app-json.json
+```
+
+BC Lantern excludes archived repositories by default. Add `--include-archived` to
+include them.
+
+The command writes one aggregate JSON file. It does not create repository
+folders or separate manifest files.
+
+### 2. Create an allocation file
+
+Create an `object_ranges.json` file with named allocations:
+
+```json
+{
+  "My team": {
+    "ranges": [
+      { "from": 1000000, "to": 1000999 }
+    ]
+  }
+}
+```
+
+Allocation ranges are inclusive. Reference allocations must not overlap.
+
+### 3. Create an object-range report
+
+Compare the collected manifests with the allocation file:
+
+```text
+bcl object-ranges report \
+  --app-json app-json.json \
+  --reference object_ranges.json \
+  --output object-range-report.json
+```
+
+Create a Markdown report:
+
+```text
+bcl object-ranges report \
+  --reference object_ranges.json \
+  --output object-range-report.md \
+  --output-format markdown
+```
+
+`--app-json` defaults to `app-json.json`. The JSON output defaults to
+`object-range-report.json`.
+
+The report compares declared reservations. It does not scan AL source files for
+implemented object IDs.
+
+## Range filters
+
+BC Lantern classifies declared ranges with these Business Central categories:
+
+| Type | Inclusive IDs |
+|---|---:|
+| `base` | 0-49,999 |
+| `customization` | 50,000-99,999 |
+| `localization` | 100,000-999,999 |
+| `rsp` | 1,000,000-69,999,999 |
+| `app` | 70,000,000-74,999,999 |
+| `unclassified` | 75,000,000 and above |
+
+Hide a category from report details but keep it in calculations:
+
+```text
+bcl object-ranges report \
+  --reference object_ranges.json \
+  --hide-range-type rsp
+```
+
+Remove a category from all calculations:
+
+```text
+bcl object-ranges report \
+  --reference object_ranges.json \
+  --ignore-range-type customization
+```
+
+Both options are repeatable. Use `--conflict-range-type` to replace the default
+set of conflict-enabled categories. By default, all categories except
+`customization` participate in conflict detection.
+
+See the [CLI reference](docs/cli-reference.md) for every command and option.
+
+## Cache
+
+BC Lantern caches GitHub metadata and manifests by default:
+
+```text
+Windows: %LOCALAPPDATA%\bc-lantern\cache
+macOS:   ~/Library/Caches/bc-lantern
+Linux:   ${XDG_CACHE_HOME:-~/.cache}/bc-lantern
+```
+
+Force a complete scan:
+
+```text
+bcl app-json retrieve --refresh
+```
+
+Disable the cache:
+
+```text
+bcl app-json retrieve --no-cache
+```
+
+Set another cache directory:
+
+```text
+bcl app-json retrieve --cache-dir path/to/cache
+```
+
+## Pipeline example
+
+Pin the package version in a pipeline:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+
+  - uses: actions/setup-python@v5
+    with:
+      python-version: "3.13"
+
+  - run: python -m pip install bc-lantern==0.7.0
+
+  - run: >-
+      bcl object-ranges report
+      --app-json app-json.json
+      --reference object_ranges.json
+      --output object-range-report.json
+```
+
+The pipeline must provide `app-json.json` and `object_ranges.json`. Alternatively,
+run `app-json retrieve` first and authenticate GitHub CLI in the pipeline.
+
+## PowerShell example
+
+[`example.ps1`](example.ps1) collects manifests and creates several reports:
+
+```powershell
+.\example.ps1 `
+  -Owner my-organization `
+  -Reference C:\path\to\object_ranges.json
+```
+
+Generated aggregates and reports are ignored by Git. They can contain repository
+metadata.
+
+## Development
+
+Install the project and its development tools:
+
+```text
+python -m pip install -e ".[dev]"
+```
+
+Run the tests:
+
+```text
+python -m pytest
+```
+
+Check the generated CLI reference:
+
+```text
+bcl docs sync --check
+```
+
+Use `bcl docs sync` after you change a command or option.
+
+## Project information
+
+- [CLI reference](docs/cli-reference.md)
+- [Contributing guide](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+- [PyPI publishing guide](docs/publishing.md)
+- [MIT License](LICENSE)