outliner-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{outliner_cli-0.1.0/src/outliner_cli.egg-info → outliner_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: outliner-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Print the structural outline of source files for LLM navigation
 Author: Per Cederberg
 License-Expression: MIT
@@ -13,19 +13,21 @@ Dynamic: license-file
 
 # outliner
 
-Print the structural outline of source files — declarations with line ranges —
-so an LLM agent (or human) can navigate a file without reading it whole.
+Print the structural outline of source files — useful declarations and callable
+landmarks with line ranges — so an LLM agent (or human) can navigate a file
+without reading it whole.
 
 ## Usage
 
 ```
-outliner [OPTIONS] [FILE...]
+outliner-cli [OPTIONS] [FILE...]
 ```
 
-| Option              | Description                                                     |
-| ------------------- | --------------------------------------------------------------- |
-| `-g, --grep EXPR`   | Only show items whose signature matches EXPR (case-insensitive) |
-| `-s, --syntax LANG` | Override syntax auto-detection when it is ambiguous             |
+| Option              | Description                                                                   |
+| ------------------- | ----------------------------------------------------------------------------- |
+| `-g, --grep EXPR`   | Only show items whose signature matches EXPR (case-insensitive)               |
+| `-s, --syntax LANG` | Override syntax auto-detection when it is ambiguous                           |
+| `-w, --width COLS`  | Truncate output lines to COLS (`0`=unlimited, `auto`=terminal, default=`120`) |
 
 Pass a file, a directory (walked recursively), or omit arguments to read stdin.
 Use `-` to read stdin explicitly. `--syntax` is only needed when content
@@ -45,7 +47,8 @@ Each line: `<start>,<count>  <signature>`
 - `start` — 1-based line number, right-aligned
 - `count` — number of lines covered by the item (including doc-comments above)
 - `signature` — first non-comment line of the declaration; multi-line signatures
-  are merged into one line
+  are merged into one line; lines longer than the output width are truncated
+  with `...`
 
 Nesting is visible in two ways: overlapping ranges (a class range contains its
 methods) and native-format indentation in the signature (indented for code,
@@ -60,14 +63,11 @@ pip install outliner
 ## Running
 
 ```sh
-# From within the outliner/ directory
-uv run outliner path/to/file.py
-
-# From the repository root
-uv run --project outliner outliner path/to/file.py
+# With the package installed (pip or uvx):
+uvx outliner-cli path/to/file.py
 
-# Outline an entire directory
-uv run --project outliner outliner src/
+# From within the outliner/ directory
+uv run outliner-cli path/to/file.py
 ```
 
 ## Running Tests
@@ -79,15 +79,17 @@ uv run pytest
 
 ## Supported Languages
 
-Python, Go, Markdown, reStructuredText — with Java, Rust, JavaScript/TypeScript,
-C/C++, C#, and many more in progress.
+AsciiDoc, C/C++, C#, Clojure, Go, HTML, Java, JavaScript/TypeScript, Markdown,
+Org-mode, Perl, PHP, Python, reStructuredText, Ruby, Rust, Scala, Shell, Swift,
+and Zig.
 
 ## Example Use Cases
 
-**Structural overview** — Run on a directory to see all declarations across many files before reading anything:
+**Structural overview** — Run on a directory to see all declarations across many
+files before reading anything:
 
 ```
-$ outliner src/
+$ uvx outliner-cli src/
 ==> src/billing.py <==
  12,8   class Invoice
  22,4   def create(customer_id: str, items: list[Item]) -> Invoice
@@ -98,10 +100,11 @@ $ outliner src/
  14,12  def charge(method: PaymentMethod, amount: Decimal) -> Receipt
 ```
 
-**Find all copies of a pattern** — `--grep serialize` across a source tree locates every implementation of a repeated function in one command:
+**Find all copies of a pattern** — `--grep serialize` across a source tree
+locates every implementation of a repeated function in one command:
 
 ```
-$ outliner --grep serialize src/
+$ uvx outliner-cli --grep serialize src/
 ==> src/invoice.py <==
  44,5   def serialize(self) -> dict
 
@@ -109,18 +112,23 @@ $ outliner --grep serialize src/
  31,3   def serialize(self) -> dict
 ```
 
-**Find functions whose interface mentions a term** — `--grep` searches signatures, not bodies. It finds functions whose interface involves a concept, skipping internal uses, comments, and call sites:
+**Find functions whose interface mentions a term** — `--grep` searches
+signatures, not bodies. It finds functions whose interface involves a concept,
+skipping internal uses, comments, and call sites:
 
 ```
-$ outliner --grep payment src/
+$ uvx outliner-cli --grep payment src/
  14,12  def charge(method: PaymentMethod, amount: Decimal) -> Receipt
  61,4   def refund(payment: Payment) -> bool
 ```
 
-**Find functions accepting a specific type** — `--grep PaymentMethod` locates every function where the type appears in parameters, return types, or generic bounds. Multi-line signatures are merged into a single line before matching, so nothing is missed:
+**Find functions accepting a specific type** — `--grep PaymentMethod` locates
+every function where the type appears in parameters, return types, or generic
+bounds. Multi-line signatures are merged into a single line before matching, so
+nothing is missed:
 
 ```
-$ outliner --grep PaymentMethod src/
+$ uvx outliner-cli --grep PaymentMethod src/
  14,12  def charge(method: PaymentMethod, amount: Decimal) -> Receipt
  88,4   def validate(m: PaymentMethod) -> bool
 ```

{outliner_cli-0.1.0 → outliner_cli-0.2.0}/README.md

@@ -1,18 +1,20 @@
 # outliner
 
-Print the structural outline of source files — declarations with line ranges —
-so an LLM agent (or human) can navigate a file without reading it whole.
+Print the structural outline of source files — useful declarations and callable
+landmarks with line ranges — so an LLM agent (or human) can navigate a file
+without reading it whole.
 
 ## Usage
 
 ```
-outliner [OPTIONS] [FILE...]
+outliner-cli [OPTIONS] [FILE...]
 ```
 
-| Option              | Description                                                     |
-| ------------------- | --------------------------------------------------------------- |
-| `-g, --grep EXPR`   | Only show items whose signature matches EXPR (case-insensitive) |
-| `-s, --syntax LANG` | Override syntax auto-detection when it is ambiguous             |
+| Option              | Description                                                                   |
+| ------------------- | ----------------------------------------------------------------------------- |
+| `-g, --grep EXPR`   | Only show items whose signature matches EXPR (case-insensitive)               |
+| `-s, --syntax LANG` | Override syntax auto-detection when it is ambiguous                           |
+| `-w, --width COLS`  | Truncate output lines to COLS (`0`=unlimited, `auto`=terminal, default=`120`) |
 
 Pass a file, a directory (walked recursively), or omit arguments to read stdin.
 Use `-` to read stdin explicitly. `--syntax` is only needed when content
@@ -32,7 +34,8 @@ Each line: `<start>,<count>  <signature>`
 - `start` — 1-based line number, right-aligned
 - `count` — number of lines covered by the item (including doc-comments above)
 - `signature` — first non-comment line of the declaration; multi-line signatures
-  are merged into one line
+  are merged into one line; lines longer than the output width are truncated
+  with `...`
 
 Nesting is visible in two ways: overlapping ranges (a class range contains its
 methods) and native-format indentation in the signature (indented for code,
@@ -47,14 +50,11 @@ pip install outliner
 ## Running
 
 ```sh
-# From within the outliner/ directory
-uv run outliner path/to/file.py
-
-# From the repository root
-uv run --project outliner outliner path/to/file.py
+# With the package installed (pip or uvx):
+uvx outliner-cli path/to/file.py
 
-# Outline an entire directory
-uv run --project outliner outliner src/
+# From within the outliner/ directory
+uv run outliner-cli path/to/file.py
 ```
 
 ## Running Tests
@@ -66,15 +66,17 @@ uv run pytest
 
 ## Supported Languages
 
-Python, Go, Markdown, reStructuredText — with Java, Rust, JavaScript/TypeScript,
-C/C++, C#, and many more in progress.
+AsciiDoc, C/C++, C#, Clojure, Go, HTML, Java, JavaScript/TypeScript, Markdown,
+Org-mode, Perl, PHP, Python, reStructuredText, Ruby, Rust, Scala, Shell, Swift,
+and Zig.
 
 ## Example Use Cases
 
-**Structural overview** — Run on a directory to see all declarations across many files before reading anything:
+**Structural overview** — Run on a directory to see all declarations across many
+files before reading anything:
 
 ```
-$ outliner src/
+$ uvx outliner-cli src/
 ==> src/billing.py <==
  12,8   class Invoice
  22,4   def create(customer_id: str, items: list[Item]) -> Invoice
@@ -85,10 +87,11 @@ $ outliner src/
  14,12  def charge(method: PaymentMethod, amount: Decimal) -> Receipt
 ```
 
-**Find all copies of a pattern** — `--grep serialize` across a source tree locates every implementation of a repeated function in one command:
+**Find all copies of a pattern** — `--grep serialize` across a source tree
+locates every implementation of a repeated function in one command:
 
 ```
-$ outliner --grep serialize src/
+$ uvx outliner-cli --grep serialize src/
 ==> src/invoice.py <==
  44,5   def serialize(self) -> dict
 
@@ -96,18 +99,23 @@ $ outliner --grep serialize src/
  31,3   def serialize(self) -> dict
 ```
 
-**Find functions whose interface mentions a term** — `--grep` searches signatures, not bodies. It finds functions whose interface involves a concept, skipping internal uses, comments, and call sites:
+**Find functions whose interface mentions a term** — `--grep` searches
+signatures, not bodies. It finds functions whose interface involves a concept,
+skipping internal uses, comments, and call sites:
 
 ```
-$ outliner --grep payment src/
+$ uvx outliner-cli --grep payment src/
  14,12  def charge(method: PaymentMethod, amount: Decimal) -> Receipt
  61,4   def refund(payment: Payment) -> bool
 ```
 
-**Find functions accepting a specific type** — `--grep PaymentMethod` locates every function where the type appears in parameters, return types, or generic bounds. Multi-line signatures are merged into a single line before matching, so nothing is missed:
+**Find functions accepting a specific type** — `--grep PaymentMethod` locates
+every function where the type appears in parameters, return types, or generic
+bounds. Multi-line signatures are merged into a single line before matching, so
+nothing is missed:
 
 ```
-$ outliner --grep PaymentMethod src/
+$ uvx outliner-cli --grep PaymentMethod src/
  14,12  def charge(method: PaymentMethod, amount: Decimal) -> Receipt
  88,4   def validate(m: PaymentMethod) -> bool
 ```

{outliner_cli-0.1.0 → outliner_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "outliner-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Print the structural outline of source files for LLM navigation"
 authors = [{name = "Per Cederberg"}]
 license = "MIT"
@@ -17,7 +17,7 @@ Homepage = "https://github.com/cederberg/incubator/tree/main/outliner"
 Repository = "https://github.com/cederberg/incubator"
 
 [project.scripts]
-outliner = "outliner.cli:main"
+outliner-cli = "outliner.cli:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]

outliner_cli-0.2.0/src/outliner/cli.py

@@ -0,0 +1,183 @@
+"""outliner — print structural outline of source files."""
+
+import argparse
+import fnmatch
+import os
+import re
+import shutil
+import sys
+
+from outliner.parsers import NAMES, EXTENSIONS, detect, outline, syntax
+from outliner.types import OutlineItem
+
+
+def die(msg: str, code: int = 2) -> None:
+    print(f"outliner: {msg}", file=sys.stderr)
+    sys.exit(code)
+
+
+def guess_syntax(src: str) -> str | None:
+    return EXTENSIONS.get(os.path.splitext(src.lower())[1])
+
+
+def _load_gitignore(dirpath: str) -> list[str]:
+    try:
+        with open(os.path.join(dirpath, ".gitignore"), encoding="utf-8", errors="replace") as f:
+            return [ln.rstrip("\n") for ln in f if ln.strip() and not ln.startswith("#")]
+    except OSError:
+        return []
+
+
+def _gitignore_match(name: str, relpath: str, patterns: list[str], is_dir: bool) -> bool:
+    result = False
+    for pat in patterns:
+        negate = pat.startswith("!")
+        p = pat[1:] if negate else pat
+        dir_only = p.endswith("/")
+        if dir_only:
+            if not is_dir:
+                continue
+            p = p[:-1]
+        target = relpath if "/" in p else name
+        if fnmatch.fnmatch(target, p.lstrip("/")):
+            result = not negate
+    return result
+
+
+def _is_ignored(name: str, root: str, gi: dict[str, list[str]], is_dir: bool) -> bool:
+    for gi_dir, pats in gi.items():
+        if gi_dir == root or root.startswith(gi_dir + os.sep):
+            rel = os.path.relpath(os.path.join(root, name), gi_dir)
+            if _gitignore_match(name, rel, pats, is_dir):
+                return True
+    return False
+
+
+def _expand_sources(sources: list[str], types: set[str] | None = None) -> list[str]:
+    result = []
+    for src in sources:
+        if src == "-" or not os.path.isdir(src):
+            result.append(src)
+            continue
+        gi: dict[str, list[str]] = {}
+        for root, dirs, files in os.walk(src):
+            pats = _load_gitignore(root)
+            if pats:
+                gi[root] = pats
+            dirs[:] = sorted(d for d in dirs if not _is_ignored(d, root, gi, True))
+            for name in sorted(files):
+                match = guess_syntax(name)
+                supported = match and (not types or match in types)
+                if supported and not _is_ignored(name, root, gi, False):
+                    result.append(os.path.join(root, name))
+    return result
+
+
+def _format_items(items: list[OutlineItem], grep: re.Pattern | None, line_width: int) -> list[str]:
+    if grep:
+        items = [it for it in items if grep.search(it.signature)]
+    if not items:
+        return []
+    num_width = max(it.num_width for it in items)
+    num_width = max(num_width, 3)
+    return [it.format(num_width, line_width) for it in items]
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="outliner",
+        description="Print the structural outline of source files.",
+    )
+    ap.add_argument("files", nargs="*", metavar="FILE",
+                    help="Files to outline (omit or use - for stdin)")
+    ap.add_argument("-g", "--grep", metavar="EXPR",
+                    help="Only show items whose signature matches EXPR (case-insensitive)")
+    ap.add_argument("-s", "--syntax", metavar="LANG",
+                    help=f"Override syntax auto-detection (available: {', '.join(NAMES)})")
+    ap.add_argument("-t", "--type", action="append", metavar="LANG",
+                    help="Only include files of this language or extension (repeatable)")
+    ap.add_argument("-w", "--width", metavar="COLS", default="120",
+                    help="Truncate output lines to COLS (0=unlimited, auto=terminal width, default=120)")
+    args = ap.parse_args(argv)
+
+    grep_re: re.Pattern | None = None
+    if args.grep:
+        try:
+            grep_re = re.compile(args.grep, re.IGNORECASE)
+        except re.error as exc:
+            die(f"invalid --grep expression: {exc}")
+
+    line_width: int
+    if args.width == "auto":
+        line_width = shutil.get_terminal_size(fallback=(120, 24)).columns
+    else:
+        try:
+            line_width = int(args.width)
+        except ValueError:
+            die(f"invalid --width value: {args.width}")
+        if line_width < 0:
+            die(f"--width must be >= 0")
+
+    if args.syntax:
+        original_syntax = args.syntax
+        args.syntax = syntax(args.syntax)
+        if args.syntax is None:
+            die(f"unknown syntax '{original_syntax}' (try a language name like 'python' or extension like '.py')")
+
+    types = None
+    if args.type:
+        types = set()
+        for name in args.type:
+            r = syntax(name)
+            if r is None:
+                die(f"unknown --type '{name}' (try a language name like 'python' or extension like '.py')")
+            types.add(r)
+
+    sources = args.files or ["-"]
+    if sources == ["-"] and sys.stdin.isatty():
+        ap.print_help()
+        return 0
+    sources = _expand_sources(sources, types)
+    multi = len(sources) > 1
+
+    exit_code = 0
+    for src in sources:
+        try:
+            if src == "-":
+                text = sys.stdin.read()
+            else:
+                with open(src, encoding="utf-8", errors="replace") as fh:
+                    text = fh.read()
+        except OSError as exc:
+            print(f"outliner: {exc}", file=sys.stderr)
+            exit_code = 1
+            continue
+
+        match = args.syntax or guess_syntax(src) or detect(text)
+
+        if match is None:
+            print(f"outliner: cannot auto-detect syntax for '{src}'; use --syntax",
+                  file=sys.stderr)
+            exit_code = 2
+            continue
+
+        items = outline(match, text)
+        if items is None:
+            available = ", ".join(NAMES)
+            print(f"outliner: unsupported syntax '{match}'; available: {available}",
+                  file=sys.stderr)
+            exit_code = 2
+            continue
+
+        output_lines = _format_items(items, grep_re, line_width)
+
+        if output_lines:
+            if multi:
+                print(f"\n==> {src} <==")
+            print("\n".join(output_lines))
+
+    return exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{outliner_cli-0.1.0 → outliner_cli-0.2.0}/src/outliner/parsers/__init__.py

@@ -1,9 +1,9 @@
 import re
 
-from . import python, scala, go, java, rust, swift, c, ruby, php, shell, javascript, csharp, perl, zig, clojure, asciidoc, orgmode, rst, markdown
+from . import python, scala, go, java, rust, swift, c, ruby, php, shell, javascript, csharp, perl, zig, clojure, html, asciidoc, orgmode, rst, markdown
 from outliner.types import OutlineItem
 
-_MODULES = [python, scala, go, java, rust, swift, c, ruby, php, shell, javascript, csharp, perl, zig, clojure, asciidoc, orgmode, rst, markdown]
+_MODULES = [python, scala, go, java, rust, swift, c, ruby, php, shell, javascript, csharp, perl, zig, clojure, html, asciidoc, orgmode, rst, markdown]
 _PARSERS = {mod.SYNTAX: mod.parse for mod in _MODULES}
 NAMES = sorted(_PARSERS)
 EXTENSIONS = {ext: mod.SYNTAX for mod in _MODULES for ext in mod.EXTENSIONS}
@@ -16,6 +16,13 @@ def _strip_frontmatter(content: str) -> str:
     return content[m.end():] if m else content
 
 
+def syntax(name: str) -> str | None:
+    if name in _PARSERS:
+        return name
+    ext = name if name.startswith(".") else "." + name
+    return EXTENSIONS.get(ext)
+
+
 def detect(content: str) -> str | None:
     lines = _strip_frontmatter(content).splitlines()[:100]
     for mod in _MODULES: