Skip to content

PYPI.md

Latest commit

 

History

History
112 lines (87 loc) · 4.94 KB

PYPI.md

File metadata and controls

112 lines (87 loc) · 4.94 KB
Raw

simplicio-mapper

README globalization release: the GitHub README now ships with 15 language entry points, Star History, ecosystem graph, and a proof-first structure. The package contract below remains the canonical PyPI technical reference.

Python-first project mapper for the Simplicio ecosystem. It scans a repository and emits machine-readable artifacts that agents and tooling can consume without parsing the human-readable markdown docs:

  • .simplicio/project-map.json (simplicio.project-map/v1) — file inventory, architecture signals, entry points, tests, modules, entities, dependencies and recent changes.
  • .simplicio/precedent-index.json (simplicio.precedent-index/v1) — high-signal code examples tagged by change type, file, language, roles and snippet.
  • .simplicio/architecture-inventory.json (simplicio.architecture-inventory/v1) — modules, layers, responsibilities, evidence pointers, tests, symbols and relationships.
  • .simplicio/symbol-index.json (simplicio.symbol-index/v1) — detected classes, functions, methods and exports with file/line evidence.
  • .simplicio/call-graph.json (simplicio.call-graph/v1) — import and heuristic caller/callee relationships with confidence scores.

The full contract is documented in SIMPLICIO_INTEGRATION.md.

Install

Requires Python 3.10+. The package installs lightweight performance dependencies (orjson for JSON serialization and diskcache for persistent file-processing cache).

pip install simplicio-mapper

Usage

# Map the current directory into .simplicio/
simplicio-mapper map

# Refresh artifacts and record changed files since the last run
simplicio-mapper update

# Idempotent orchestration entry point for SendSprint and other runners
simplicio-mapper index path/to/project --json
simplicio-mapper index --update path/to/project --json

# Compare frontend/API-client calls against runtime server routes
simplicio-mapper endpoints path/to/web --against path/to/api --json

# Render architecture inventory markdown for wiki/docs review
simplicio-mapper docs path/to/project --json
simplicio-mapper export-docs path/to/project --target ./wiki-export --json
simplicio-mapper index path/to/project --docs --background

# Map another project root, with hints when .starter-meta.json is absent
simplicio-mapper map --root path/to/project --stack python --product-name "My App"

# Re-run automatically while files change locally
simplicio-mapper map --watch

The llm-project-mapper console script is provided as an alias.

Options

Option Description
index <path> Scriptable index command. Returns 0 when refreshed or already fresh, 1 on failure. Quiet by default.
endpoints <path> Extract normalized client calls and server routes, including Python API clients, direct page-level Python calls and Angular HttpClient services. Use --against <server-root> to report missing_from_server with source files using schema simplicio.endpoint-inventory/v1.
docs <path> Render architecture inventory Markdown under .simplicio/docs/.
export-docs <path> Copy rendered Markdown docs to a local target directory. Remote publication is intentionally opt-in and not automatic.
--against <dir> Server/API project root for endpoint comparison.
--target <dir> Local target directory for export-docs.
--docs Render Markdown docs after map or index.
--no-docs Keep map/index JSON-only.
--docs-only Render the Markdown docs without emitting the index JSON payload.
--json-only Compatibility alias for keeping map/index JSON-only.
--changed-only Compatibility alias for incremental refresh workflows.
--background Start a detached index refresh and write .simplicio/background-index.log.
--json Emit stable simplicio.mapper-index/v1 output for the index command.
--update Compatibility alias for index refresh workflows.
--verbose Show progress during index refreshes.
--root <dir> Project root to map. Defaults to the current directory.
--out <dir> Artifact directory. Defaults to .simplicio.
--stack <name> Stack hint when .starter-meta.json is absent.
--product-name <name> Product name hint when .starter-meta.json is absent.
--incremental Record changed files and update existing artifacts.
--watch Re-run mapping when local files change.
--silent Minimal output.
-V, --version Show version and exit.
-h, --help Show help.

Consuming the artifacts

from pathlib import Path
import json

base = Path(".simplicio")
project_map = json.loads((base / "project-map.json").read_text())
precedents = json.loads((base / "precedent-index.json").read_text())

top_files = sorted(
    project_map["files"], key=lambda f: f.get("importance", 0), reverse=True
)[:8]

License

MIT