repotour 1.0.0__tar.gz

repotour-1.0.0/.gitattributes

@@ -0,0 +1,4 @@
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+repotour/render/vendor/** -text -diff linguist-vendored

repotour-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,45 @@
+name: Bug report
+description: Something in Repotour doesn't work as expected
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What you ran, what you expected, and what you got instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How to reproduce
+      description: Ideally a public repository and commit where it happens, plus the exact command.
+      placeholder: |
+        1. git clone https://github.com/example/project && git -C project checkout <sha>
+        2. repotour project
+    validations:
+      required: true
+  - type: textarea
+    id: wrong-claim
+    attributes:
+      label: Wrong claim (if any)
+      description: If the tour said something wrong, paste the claim and its evidence.
+  - type: input
+    id: version
+    attributes:
+      label: Repotour version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options: [Linux, macOS, Windows]
+    validations:
+      required: true
+  - type: input
+    id: git-version
+    attributes:
+      label: git version
+      placeholder: "2.45.0"

repotour-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/babarshahzad2005/repotour/security/advisories/new
+    about: Please report security issues privately, not as public issues.

repotour-1.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature request
+description: Suggest an improvement to the tour or the tool
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+      description: Describe the newcomer question or maintainer need that isn't served today.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: What evidence would back it?
+      description: Every claim in a tour points to evidence (a file, a commit range, an import). What would this feature cite?

repotour-1.0.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      python-dependencies:
+        patterns: ["*"]
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "ci(deps)"
+    groups:
+      github-actions:
+        patterns: ["*"]

repotour-1.0.0/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Summary
+
+<!-- What does this change do, and why? Link the issue if there is one. -->
+
+## How it was tested
+
+<!-- Tests added or updated, fixture repositories used, manual checks. -->
+
+## Checklist
+
+- [ ] Tests added or updated (fixture-repository tests for new behavior)
+- [ ] Golden tours updated with `uv run pytest --update-goldens` and the diff reviewed, if output changed
+- [ ] Every new claim in the tour carries evidence
+- [ ] Docs updated if behavior or design changed (`docs/design/`, `GLOSSARY.md`, ADRs)
+- [ ] `CHANGELOG.md` updated for user-visible changes

repotour-1.0.0/.github/workflows/action.yml

@@ -0,0 +1,68 @@
+name: Action
+
+# Runs this repository's own GitHub Action against itself, without opening a
+# pull request, whenever the action or the code it installs changes.
+on:
+  pull_request:
+    paths:
+      - "action.yml"
+      - "repotour/**"
+      - "pyproject.toml"
+      - ".github/workflows/action.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  dry-run:
+    name: dry run (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: markdown
+        uses: ./
+        with:
+          dry-run: "true"
+      - id: html
+        uses: ./
+        with:
+          format: html
+          path: site/TOUR.html
+          dry-run: "true"
+      - name: Check the outputs
+        shell: bash
+        env:
+          MD_CHANGED: ${{ steps.markdown.outputs.changed }}
+          HTML_CHANGED: ${{ steps.html.outputs.changed }}
+          PR_URL: ${{ steps.markdown.outputs.pull-request }}
+        run: |
+          test "$MD_CHANGED" = "true"
+          test "$HTML_CHANGED" = "true"
+          test -z "$PR_URL"
+          head -1 TOUR.md | grep -qx "<!-- generated by repotour -->"
+          grep -q "<!doctype html>" site/TOUR.html
+
+  shallow-clone:
+    name: shallow clone is refused
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+      - id: tour
+        uses: ./
+        continue-on-error: true
+        with:
+          dry-run: "true"
+      - name: Expect a failure
+        shell: bash
+        env:
+          OUTCOME: ${{ steps.tour.outcome }}
+        run: test "$OUTCOME" = "failure"

repotour-1.0.0/.github/workflows/benchmarks.yml

@@ -0,0 +1,30 @@
+name: Benchmarks
+
+# Performance targets are measured on real repositories pinned to exact
+# commits. Not run on every push: weekly, on demand, and when the benchmark
+# itself changes.
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1"
+  pull_request:
+    paths:
+      - "benchmarks/**"
+      - ".github/workflows/benchmarks.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  benchmark:
+    name: benchmark (ubuntu-latest)
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+      - run: uv sync --locked
+      - name: Run benchmarks
+        run: uv run python benchmarks/run.py --dir "$RUNNER_TEMP/bench"

repotour-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.11"
+      - run: uv sync --locked
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv run mypy
+
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run pytest
+      - name: Verify goldens are unchanged
+        shell: bash
+        run: git diff --exit-code -- tests/golden
+
+  # Single required check for branch protection.
+  ci-ok:
+    name: ci-ok
+    if: always()
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    steps:
+      - name: All jobs passed
+        run: |
+          test "${{ needs.lint.result }}" = "success"
+          test "${{ needs.test.result }}" = "success"

repotour-1.0.0/.github/workflows/corpus.yml

@@ -0,0 +1,35 @@
+name: Corpus
+
+# Tours 20 real repositories pinned in tests/corpus.yml and fails on any
+# crash. Weekly, on demand, and when the corpus or its runner changes.
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 7 * * 1"
+  pull_request:
+    paths:
+      - "tests/corpus.yml"
+      - "benchmarks/corpus.py"
+      - ".github/workflows/corpus.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  corpus:
+    name: corpus (ubuntu-latest)
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+      - run: uv sync --locked
+      - name: Tour every corpus repository
+        run: uv run python benchmarks/corpus.py --dir "$RUNNER_TEMP/corpus"
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: corpus-tours
+          path: ${{ runner.temp }}/corpus/tours/*.md

repotour-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,102 @@
+name: Release
+
+# Builds the package once, checks that the built wheel installs and runs on
+# every supported platform, then publishes it with PyPI trusted publishing
+# (no stored token). Run it by hand to publish to TestPyPI first; publishing
+# a GitHub release publishes to PyPI.
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+      - name: Check the tag matches the version
+        if: github.event_name == 'release'
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          version=$(uv run --no-project python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          test "$TAG" = "v$version" || { echo "::error::Tag $TAG does not match version $version"; exit 1; }
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  smoke-test:
+    name: smoke test (${{ matrix.os }}, py${{ matrix.python }})
+    needs: build
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - name: Install the wheel and tour this repository
+        shell: bash
+        run: |
+          python -m pip install --disable-pip-version-check dist/*.whl
+          cd "$RUNNER_TEMP"
+          repotour --help
+          repotour "$GITHUB_WORKSPACE" --out tour.md --format md
+          repotour "$GITHUB_WORKSPACE" --out tour.html --format html --json tour.json
+          head -1 tour.md | grep -qx "<!-- generated by repotour -->"
+
+  testpypi:
+    name: publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch'
+    needs: smoke-test
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/repotour/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  pypi:
+    name: publish to PyPI
+    if: github.event_name == 'release'
+    needs: smoke-test
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/repotour/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

repotour-1.0.0/.github/workflows/samples.yml

@@ -0,0 +1,34 @@
+name: Sample tours
+
+# Generates the published sample tours (Flask, Express, fzf at pinned commits)
+# and uploads them as an artifact for review. Runs on demand and whenever
+# product code or the generator changes, so every code change is also checked
+# against three real repositories.
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - "repotour/**"
+      - "benchmarks/samples.py"
+      - ".github/workflows/samples.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  samples:
+    name: sample tours
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+      - run: uv sync --locked
+      - name: Generate sample tours
+        run: uv run python benchmarks/samples.py --dir "$RUNNER_TEMP/samples" --out sample-tours
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sample-tours
+          path: sample-tours/*.md

repotour-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

repotour-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+# Hooks run the project's own pinned tools through uv, so local checks match CI.
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run --frozen ruff check --fix
+        language: system
+        types_or: [python, markdown]
+      - id: ruff-format
+        name: ruff format
+        entry: uv run --frozen ruff format
+        language: system
+        types_or: [python, markdown]
+      - id: mypy
+        name: mypy
+        entry: uv run --frozen mypy
+        language: system
+        types: [python]
+        pass_filenames: false

repotour-1.0.0/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-11-15
+
+First stable release (M4): HTML and JSON output, AI summaries, the GitHub Action, and PyPI packages. Every quality, performance, and robustness target in the plan is met.
+
+### Added
+
+- Published on PyPI: `pip install repotour`. Releases are built once, smoke-tested on Linux, macOS, and Windows, and published with trusted publishing.
+- README with sample tours, benchmarks and their method, Action setup, and how AI summaries handle your code. The Flask, Express, and fzf sample tours are regenerated with 1.0.0 (reading orders unchanged since review).
+- GitHub Action: on each release (or on demand) it regenerates the tour and opens or updates one "Update codebase tour" pull request, or none if nothing changed. It caches the analysis between runs, refuses shallow clones with a clear message, and turns on AI summaries when given an `llm-api-key` secret. See `docs/action.md`.
+- Summaries handle free-tier rate limits: a "too many requests" answer is waited out as the provider asks, up to 5 minutes per run, then the remaining files are skipped with one warning.
+- `--summaries` adds a short AI-written paragraph about each key file (reading order first, then core modules, at most 15), in a section clearly labelled as AI-generated, in Markdown, HTML, and JSON. Providers are presets in `.repotour.yml`: Groq (default), OpenRouter, Ollama, or any OpenAI-compatible endpoint; each user brings their own key from the environment. Repotour prints what it will send and where before sending, caches summaries by file content and model, and turns every failure into a warning. Without the flag it never uses the network. See `docs/configuration.md`.
+- `--format html` writes one self-contained `TOUR.html` that works offline: the dependency graph is drawn by an embedded, pinned Mermaid bundle (`@mermaid-js/tiny` 12.3.0, checked by hash), it adapts to light and dark mode, and text from the repository is always escaped. The page is built from the Markdown tour, so both formats say the same thing.
+- `--json FILE` also writes the tour model as JSON with a `schema_version`, for tools rather than people. The format is experimental; see `docs/json.md`. It is byte-identical across platforms and, like the tour, never overwrites a file Repotour did not write.
+- Incremental benchmark: after touring the previous release, re-touring the next one (Flask 3.1.2 to 3.1.3, fzf v0.74.0 to v0.75.0, Go 1.27.0 to 1.27.3) is timed against a 5-second target, and the result must be byte-identical to a cold tour.
+
+### Changed
+
+- Re-running after a release is much faster on large repositories: golang/go went from 29 s to 4.8 s, and its first run from 59 s to 45 s. Cached history uses a compact format and is decoded without generic type resolution, renames are followed once per tour, and hot paths handle repository paths as plain strings. Existing caches are rebuilt once.
+- The project is marked Production/Stable.
+
+## [0.3.0] - 2026-11-08
+
+Third milestone (M3): dependency graph, entry points, and the reading order.
+
+### Added
+
+- Sample tours of Flask, Express, and fzf at pinned release commits in `docs/samples/`, reviewed against a written reading-order rubric (`docs/rubric.md`): 4/5, 4/5, and 5/5.
+- Robustness corpus: 20 real repositories (Python, JavaScript/TypeScript, Go, a monorepo, heavy vendoring and migrations, Django, a Rust repository, and a shallow clone) toured weekly in CI with zero crashes.
+- Large-repository benchmark: golang/go tours in 59 s against a 2-minute target; Kubernetes is reported as a stretch target.
+- Start here: up to five files to read first, in order. Pinned entry points come first, then execution entry points, then public surfaces; within each group files rank by PageRank and hotspot percentiles. After the first entry point, each next file is the best one imported by a file already chosen. Every reason comes from real signals (entry point, imported by, importer count, repeated changes), and the list is never padded.
+- Go in the dependency graph and entry points: imports resolve through every `go.mod` module path (covering `go.work` workspaces), linking to one representative file of the imported package (ADR-0005); files of an imported package are never called leaf modules. Entry points: `package main` programs, `ListenAndServe` servers, and each module's root package.
+- JavaScript and TypeScript in the dependency graph and entry points: static `import`/`export ... from`/`require('literal')` (and TypeScript `import x = require()`), resolved through relative paths with extension inference and index files, `tsconfig.json` `paths`/`baseUrl`, and workspace packages; entry points from `package.json` `main`/`module`/`exports`/`bin`, server startup (`.listen()`), and `require.main === module`.
+- Core and leaf modules: Repotour's own deterministic PageRank names the most depended-on modules; modules nothing imports (that are not entry points or empty) are listed as safe places for a first change.
+- Large dependency graphs collapse to directories, one level coarser at a time, to at most `thresholds.graph_max_nodes` (60) nodes; if even the top level is too big, the highest-ranked directories are kept and the rest counted. `--full-graph` (or `full_graph: true`) draws every module.
+- Per-file parse cache: parse results are cached by content hash and language adapter version, so a re-run parses only changed files (a moved but unchanged file is never re-parsed). Within one run, each file is parsed once and shared by all analyzers.
+- Entry points section: where execution starts (scripts, CLIs, servers, web apps, `python -m` modules, console scripts) and the public surface (top-level packages), plus commands from `package.json`, `Dockerfile`, and `Cargo.toml` that point at real files, in any language. Pinned entry points from config come first; each kind is capped at 10.
+- Dependency graph section (Python): static imports parsed with tree-sitter and resolved to repository files (relative imports, top-level packages, `src/` layout), rendered as a Mermaid diagram that displays on GitHub. Every edge cites its import; external modules are counted; test, generated, and vendored files are left out; unparseable files become warnings.
+
+### Fixed
+
+- Files with syntax the parser does not fully know (for example newer TypeScript) keep the imports and entry points it recovered, with one summary warning instead of being dropped from the graph one warning at a time.
+- Binary and oversized files only produce a warning when they are code in a known language; translation files, archives, wheels, and data files are counted silently (Django went from 1,315 warnings to a handful).
+- Example, documentation, and benchmark code no longer leads the reading order or entry points, and is never a core or leaf module.
+- A `package.json` without `main` or `exports` is treated as Node does (`index.js`), so such packages are libraries with a public surface.
+- `require('../..')` resolves to the directory's index file; unresolved relative imports are no longer counted as external packages.
+- `python -m` names use the package's source root.
+- GitHub Actions expressions are no longer quoted as commands; continued Makefile recipe lines end with an ellipsis; Go library evidence names each package once.
+
+## [0.2.0] - 2026-11-07
+
+Second milestone (M2): history and ownership.
+
+### Added
+
+- Hotspots section: the files changed most often in the hotspot window, measured back from HEAD's commit date (`--since`, default 6 months), each citing its commit range. Merge commits, generated and vendored files, and files no longer tracked are left out.
+- Ownership section: for directories up to depth 2 with at least 5 source or test files, the top authors by share of changed lines (names only, never emails) and contacts who committed there in the 12 months before HEAD. Authors are merged only through `.mailmap`; bots (`[bot]` names and config `bots`) and bulk commits are left out; renamed files count toward their current directory.
+- Bus-factor warnings in the Ownership section when one author made more than 80% of a directory's changes and it has at least 5 files and 10 commits (all configurable). Each directory is marked active (changed inside the hotspot window) or stable (no change in 12 months).
+- Incremental history: the cache keeps the last toured commit's history, so after pulling only the new commits are read from git; rewritten history is read in full, and changing `--since` never re-reads git. History is kept in one canonical order, so incremental and cold runs give identical tours.
+- Bulk commits (more files than `thresholds.bulk_commit_files`, default 200, or listed in `.git-blame-ignore-revs` or config `ignore_revs`) are left out of the history-based sections, and the tour says how many with examples.
+- Renamed and moved files keep their history: renames are detected in the same `git log` pass and chained to the path at HEAD.
+- `python -m repotour` entry point.
+- Benchmarks on Flask and fzf at pinned commits, run weekly in CI (median of three cold runs: 0.69 s and 1.09 s against a 10 s target).
+
+## [0.1.0] - 2026-11-07
+
+First milestone (M1): the CLI skeleton and the overview section.
+
+### Fixed
+
+- A top-level directory that holds only submodules is summarized as such instead of "0 files".
+- Generated-file headers only count inside a comment at the start of a line, so prose that mentions the marker is no longer misclassified.
+
+### Added
+
+- `repotour` command that writes `TOUR.md` with the tour's metadata (repository name, HEAD commit, tool version), as deterministic UTF-8 with LF line endings on every platform.
+- `--out` option to write the tour to another path.
+- Exit code 1 with a clear message when the path is not inside a git repository, git is missing or older than 2.30, or the repository has no commits.
+- Any directory inside a repository tours the whole repository.
+- A shallow clone produces the tour with a "history truncated" warning.
+- The CLI notes when uncommitted changes are ignored; the tour always describes HEAD.
+- `.repotour.yml` configuration: `version: 1` required, unknown keys and wrong types exit 2 naming the key, optional `name:` override, and the config hash shown in the tour. See `docs/configuration.md`.
+- `--since` option for the hotspot window, overriding the config file.
+- Generated tours start with a `<!-- generated by repotour -->` marker; an existing file without it is never overwritten (exit 4) unless `--force` is given.
+- Warnings render in a closing Warnings section and are counted in the CLI summary; `--strict` exits 3 when any warning was produced.
+- Overview section: repository size and a language breakdown, each language citing its largest files. Content is read from the commit, never the working tree.
+- Analyzer pipeline: analyzers run in dependency order; a failing analyzer becomes a warning and an unavailable section instead of stopping the run.
+- File classification: generated and vendored files (from `.gitattributes`, well-known paths, lockfiles, generated-file headers, and config `exclude`) are left out of languages and size and listed with their reasons. Tests are recognized by directory, file name, and config `test_patterns`.
+- Binary files and files over 1 MB are skipped; unexpected ones are reported as warnings. Git LFS pointers count as other files; submodules are listed but never entered.
+- Analysis cache in the git common directory (shared by worktrees, never tracked, safe to delete): re-running on the same commit and config renders without re-scanning. `--no-cache` neither reads nor writes it.
+- Project types (web app, library, CLI, monorepo) detected from manifests and build files, each with evidence, or "unknown". Monorepo packages from npm/pnpm workspaces, `go.work`, Cargo workspaces, or manifests in several top-level directories.
+- "How to work on it": install, run, and test commands quoted from Makefile/justfile targets, package.json scripts, pyproject task runners, tox, nox, and GitHub Actions steps, each citing its source; the highest-priority source wins per purpose, and the tour says so when none are found.
+- Top-level directories with a one-line purpose, taken from a config note, the directory's README, a table of well-known names, or a summary of its files, and showing where each came from. Notes on other paths render as maintainer notes; a note for a missing path is a warning.
+- Missing basics: the overview flags a missing README, tests, contributing guide, license, or CI configuration, saying what was looked for.
+- Contributor documentation, code of conduct, security policy, and issue and pull request templates.
+
+[Unreleased]: https://github.com/babarshahzad2005/repotour/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/babarshahzad2005/repotour/compare/v0.3.0...v1.0.0
+[0.3.0]: https://github.com/babarshahzad2005/repotour/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/babarshahzad2005/repotour/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/babarshahzad2005/repotour/releases/tag/v0.1.0

repotour-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of Conduct
+
+This project adopts the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) as its code of conduct.
+
+In short: be respectful, assume good intent, welcome newcomers, and keep discussion focused on the work. Harassment, personal attacks, and discriminatory language are not tolerated in any project space, including issues, pull requests, and discussions.
+
+## Reporting
+
+Report unacceptable behavior privately to the maintainer at babarshahzad2005@gmail.com. Reports are handled confidentially, and the maintainer will respond as described in the Contributor Covenant's enforcement guidelines.

repotour-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing to Repotour
+
+Thanks for your interest in improving Repotour. This guide covers setup, the development loop, and how changes get merged.
+
+## Before you start
+
+- Read the [vision](docs/design/vision.md) and [architecture](docs/design/architecture.md). The architecture's "Rules every change must follow" section is binding.
+- Use the project's vocabulary from the [glossary](GLOSSARY.md) in code, tests, and docs.
+- Check the [architecture decision records](docs/adr/) before changing anything they cover. To reverse a decision, propose a new ADR.
+- For anything bigger than a small fix, open an issue first so we can agree on the approach.
+
+## Setup
+
+Requirements: Python 3.11+, git 2.30+, and [uv](https://docs.astral.sh/uv/).
+
+```sh
+git clone https://github.com/babarshahzad2005/repotour.git
+cd repotour
+uv sync
+uv run pre-commit install
+```
+
+## Development loop
+
+```sh
+uv run pytest            # tests
+uv run ruff check        # lint
+uv run ruff format       # format
+uv run mypy              # type-check (strict)
+uv run repotour          # run the CLI on the current repository
+```
+
+The pre-commit hooks run ruff and mypy on every commit.
+
+### Tests
+
+- Write the test first. Behavior is tested through fixture repositories with scripted history (see `tests/fixtures/`), never against real-world repositories.
+- New behavior gets a fixture-repository test and, if the tour output changes, an updated golden tour.
+- To update golden tours after an intentional output change, run `uv run pytest --update-goldens` and review the diff in `tests/golden/` carefully. It is part of your change.
+- Output must stay deterministic: sort everything, break ties by path, and never add timestamps.
+
+## Commits and pull requests
+
+- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`, `ci:`.
+- One topic per pull request, on a short-lived branch from `main`.
+- `main` is protected. Pull requests merge by squash once CI passes on Linux, macOS, and Windows.
+- Add a line to the `Unreleased` section of [CHANGELOG.md](CHANGELOG.md) for user-visible changes.
+
+## Reporting bugs and security issues
+
+- Bugs and feature requests: use the [issue templates](https://github.com/babarshahzad2005/repotour/issues/new/choose).
+- Security vulnerabilities: do not open a public issue. See [SECURITY.md](SECURITY.md).
+
+## Code of conduct
+
+Participation in this project is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).