sourcesage-cli

name

sourcesage-cli

description

Generate AI-friendly repository documentation with the SourceSage CLI. Use when Codex needs to run `sage` or `sourcesage` to create `.SourceSageAssets/Repository_summary.md`, analyze the current repository or another local repository, switch the output language between English and Japanese, use `--lite` to keep the summary small, change the output directory, or optionally create a deprecated tag-diff release report with `--diff`.

SourceSage CLI

Overview

Use the SourceSage CLI from this repository checkout to generate repository summaries for the current repo or another local repo.

Prefer the local checkout over assuming sourcesage is globally installed. In this repository layout, the SourceSage tool root is the directory that contains this SKILL.md.

Workflow

1. Resolve the SourceSage tool root and the target repository.

   • If the user did not specify another repo, analyze the current workspace.
   • If the current workspace is not the SourceSage repo, run SourceSage from its own checkout with uv run --directory <sourcesage-root> sage ....

2. Pick the smallest command that satisfies the request.

   • Current repo summary: uv run sage
   • Current repo summary in lite mode: uv run sage --lite
   • Current repo summary in Japanese: uv run sage -l ja
   • Another repo with default output inside that repo: uv run --directory <sourcesage-root> sage --repo "<target-repo>"
   • Another repo in lite mode: uv run --directory <sourcesage-root> sage --repo "<target-repo>" --lite
   • Another repo with explicit output directory: uv run --directory <sourcesage-root> sage --repo "<target-repo>" -o "<output-dir>"
   • Deprecated diff report: uv run --directory <sourcesage-root> sage --repo "<target-repo>" --diff

3. Verify the generated artifacts after every run.

   • Repository summary: <output-dir>/.SourceSageAssets/Repository_summary.md
   • Deprecated diff report: <output-dir>/.SourceSageAssets/RELEASE_REPORT/Report_<latest-tag>.md
   • Open the generated markdown and summarize the important results instead of only reporting that the command ran.
   • In --lite mode, confirm the summary keeps the tree, Git info, statistics, and root README files while omitting the ## File Contents section.

4. Report side effects and command mismatches.

   • Expect SourceSage to create <repo>/.SourceSageignore if it does not exist.
   • Treat --ignore-file as the supported ignore override.
   • Do not rely on --use-ignore unless the CLI is updated and re-verified, because the current CLI does not expose that flag.

Command Notes

• Prefer uv run sage inside the SourceSage repo because pyproject.toml defines both sage and sourcesage entry points.
• Prefer uv run --directory <sourcesage-root> sage ... outside the SourceSage repo so the command uses this checkout without requiring a global install.
• Fall back to sourcesage or sage directly only when the package is already installed and uv is unavailable.
• Use -l ja or -l en for output language.
• Use --lite for first-pass exploration when ignore rules are not tuned yet or when full file excerpts would make the summary too large.
• Use -o when the user wants artifacts outside the repo root.
• Use --repo to analyze another repository from this checkout.

Validation

• Run the chosen command instead of only describing it.
• Confirm that the expected markdown file exists.
• Read the generated output and report the path plus a short summary of what was produced.
• Re-run the exact command after changing any execution instructions or docs that mention it.

Avoid

• Do not assume README examples are authoritative when they differ from sourcesage/cli.py.
• Do not overwrite existing artifacts silently when the user asked for a specific destination and it already contains results.
• Do not describe SourceSage usage from memory when you can inspect pyproject.toml and sourcesage/cli.py in this repo.