outliner-cli 0.1.0__tar.gz

outliner_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Per Cederberg
+
+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.

outliner_cli-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: outliner-cli
+Version: 0.1.0
+Summary: Print the structural outline of source files for LLM navigation
+Author: Per Cederberg
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cederberg/incubator/tree/main/outliner
+Project-URL: Repository, https://github.com/cederberg/incubator
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+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.
+
+## Usage
+
+```
+outliner [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             |
+
+Pass a file, a directory (walked recursively), or omit arguments to read stdin.
+Use `-` to read stdin explicitly. `--syntax` is only needed when content
+auto-detection cannot identify the language (e.g. an ambiguous extensionless
+script piped on stdin).
+
+## Output
+
+```
+ 3,4   type Driver struct
+19,6   func New() *Driver
+26,12  func (d *Driver) StartLogging(ctx context.Context, f *os.File) error
+```
+
+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
+
+Nesting is visible in two ways: overlapping ranges (a class range contains its
+methods) and native-format indentation in the signature (indented for code,
+`#`/`##` heading levels for Markdown).
+
+## Installation
+
+```sh
+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
+
+# Outline an entire directory
+uv run --project outliner outliner src/
+```
+
+## Running Tests
+
+```sh
+# From within the outliner/ directory
+uv run pytest
+```
+
+## Supported Languages
+
+Python, Go, Markdown, reStructuredText — with Java, Rust, JavaScript/TypeScript,
+C/C++, C#, and many more in progress.
+
+## Example Use Cases
+
+**Structural overview** — Run on a directory to see all declarations across many files before reading anything:
+
+```
+$ outliner src/
+==> src/billing.py <==
+ 12,8   class Invoice
+ 22,4   def create(customer_id: str, items: list[Item]) -> Invoice
+ 38,6   def send(invoice: Invoice, method: str) -> bool
+
+==> src/payments.py <==
+  8,3   class PaymentMethod
+ 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:
+
+```
+$ outliner --grep serialize src/
+==> src/invoice.py <==
+ 44,5   def serialize(self) -> dict
+
+==> src/receipt.py <==
+ 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:
+
+```
+$ outliner --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:
+
+```
+$ outliner --grep PaymentMethod src/
+ 14,12  def charge(method: PaymentMethod, amount: Decimal) -> Receipt
+ 88,4   def validate(m: PaymentMethod) -> bool
+```

outliner_cli-0.1.0/README.md

@@ -0,0 +1,113 @@
+# 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.
+
+## Usage
+
+```
+outliner [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             |
+
+Pass a file, a directory (walked recursively), or omit arguments to read stdin.
+Use `-` to read stdin explicitly. `--syntax` is only needed when content
+auto-detection cannot identify the language (e.g. an ambiguous extensionless
+script piped on stdin).
+
+## Output
+
+```
+ 3,4   type Driver struct
+19,6   func New() *Driver
+26,12  func (d *Driver) StartLogging(ctx context.Context, f *os.File) error
+```
+
+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
+
+Nesting is visible in two ways: overlapping ranges (a class range contains its
+methods) and native-format indentation in the signature (indented for code,
+`#`/`##` heading levels for Markdown).
+
+## Installation
+
+```sh
+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
+
+# Outline an entire directory
+uv run --project outliner outliner src/
+```
+
+## Running Tests
+
+```sh
+# From within the outliner/ directory
+uv run pytest
+```
+
+## Supported Languages
+
+Python, Go, Markdown, reStructuredText — with Java, Rust, JavaScript/TypeScript,
+C/C++, C#, and many more in progress.
+
+## Example Use Cases
+
+**Structural overview** — Run on a directory to see all declarations across many files before reading anything:
+
+```
+$ outliner src/
+==> src/billing.py <==
+ 12,8   class Invoice
+ 22,4   def create(customer_id: str, items: list[Item]) -> Invoice
+ 38,6   def send(invoice: Invoice, method: str) -> bool
+
+==> src/payments.py <==
+  8,3   class PaymentMethod
+ 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:
+
+```
+$ outliner --grep serialize src/
+==> src/invoice.py <==
+ 44,5   def serialize(self) -> dict
+
+==> src/receipt.py <==
+ 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:
+
+```
+$ outliner --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:
+
+```
+$ outliner --grep PaymentMethod src/
+ 14,12  def charge(method: PaymentMethod, amount: Decimal) -> Receipt
+ 88,4   def validate(m: PaymentMethod) -> bool
+```

outliner_cli-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "outliner-cli"
+version = "0.1.0"
+description = "Print the structural outline of source files for LLM navigation"
+authors = [{name = "Per Cederberg"}]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/cederberg/incubator/tree/main/outliner"
+Repository = "https://github.com/cederberg/incubator"
+
+[project.scripts]
+outliner = "outliner.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]

outliner_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

outliner_cli-0.1.0/src/outliner/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

outliner_cli-0.1.0/src/outliner/cli.py

@@ -0,0 +1,115 @@
+"""outliner — print structural outline of source files."""
+
+import argparse
+import os
+import re
+import sys
+
+from outliner.parsers import NAMES, EXTENSIONS, detect, outline
+from outliner.types import OutlineItem
+
+
+def guess_syntax(src: str) -> str | None:
+    return EXTENSIONS.get(os.path.splitext(src.lower())[1])
+
+
+def _expand_sources(sources: list[str]) -> list[str]:
+    result = []
+    for src in sources:
+        if src == "-" or not os.path.isdir(src):
+            result.append(src)
+            continue
+        for root, dirs, files in os.walk(src):
+            dirs.sort()
+            for name in sorted(files):
+                if os.path.splitext(name.lower())[1] in EXTENSIONS:
+                    result.append(os.path.join(root, name))
+    return result
+
+
+def _format_items(items: list[OutlineItem], grep: re.Pattern | None) -> list[str]:
+    if grep:
+        items = [it for it in items if grep.search(it.signature)]
+    if not items:
+        return []
+
+    max_start_width = max(3, max(len(str(it.start)) for it in items))
+    max_field_width = 2 * max_start_width + 1
+
+    lines = []
+    for it in items:
+        start_str = str(it.start).rjust(max_start_width)
+        combined = f"{start_str},{it.count}"
+        lines.append(f"{combined.ljust(max_field_width)}  {it.signature}")
+    return lines
+
+
+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)})")
+    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:
+            print(f"outliner: invalid --grep expression: {exc}", file=sys.stderr)
+            return 2
+
+    sources = args.files or ["-"]
+    if sources == ["-"] and sys.stdin.isatty():
+        ap.print_help()
+        return 0
+    sources = _expand_sources(sources)
+    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
+
+        syntax = args.syntax or guess_syntax(src) or detect(text)
+
+        if syntax is None:
+            print(f"outliner: cannot auto-detect syntax for '{src}'; use --syntax",
+                  file=sys.stderr)
+            exit_code = 2
+            continue
+
+        items = outline(syntax, text)
+        if items is None:
+            available = ", ".join(NAMES)
+            print(f"outliner: unsupported syntax '{syntax}'; available: {available}",
+                  file=sys.stderr)
+            exit_code = 2
+            continue
+
+        output_lines = _format_items(items, grep_re)
+
+        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/src/outliner/parsers/__init__.py

@@ -0,0 +1,36 @@
+import re
+
+from . import python, scala, go, java, rust, swift, c, ruby, php, shell, javascript, csharp, perl, zig, clojure, 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]
+_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}
+
+_FRONTMATTER_RE = re.compile(r'\A(?:---\n(?:.*\n){0,98}?---\n|\+\+\+\n(?:.*\n){0,98}?\+\+\+\n)')
+
+
+def _strip_frontmatter(content: str) -> str:
+    m = _FRONTMATTER_RE.match(content)
+    return content[m.end():] if m else content
+
+
+def detect(content: str) -> str | None:
+    lines = _strip_frontmatter(content).splitlines()[:100]
+    for mod in _MODULES:
+        if mod.detect(lines):
+            return mod.SYNTAX
+    return None
+
+
+def outline(syntax: str, content: str) -> list[OutlineItem] | None:
+    parse = _PARSERS.get(syntax)
+    if not parse:
+        return None
+    m = _FRONTMATTER_RE.match(content)
+    if not m:
+        return list(parse(content))
+    offset = m.group(0).count('\n')
+    return [OutlineItem(start=it.start + offset, count=it.count, signature=it.signature)
+            for it in parse(content[m.end():])]

outliner_cli-0.1.0/src/outliner/parsers/asciidoc.py

@@ -0,0 +1,89 @@
+"""AsciiDoc outline parser.
+
+Recognises ATX-style headings prefixed with one or more `=` characters
+followed by a space (``= Title``, ``== Section``, ``=== Subsection``, …).
+The number of `=` signs determines the heading level; level 0 (`=`) is
+the document title.  Each heading's range extends to the line before the
+next heading at the same or higher level (lower `=` count), or to EOF.
+
+Content detection looks for AsciiDoc-specific co-occurring markers:
+  - a document-title line (``= `` at column 0) together with attribute
+    entries (``:attr:`` lines) or block macros (``[source,…]``, ``[NOTE]``,
+    ``[TIP]``, etc.)
+  - block macros alone are sufficient (``[source,lang]`` / ``[NOTE]``)
+"""
+
+import re
+from collections.abc import Iterator
+
+from outliner.types import OutlineItem
+from outliner.parsers.util import extract_summary
+
+SYNTAX = "asciidoc"
+EXTENSIONS = (".adoc", ".asciidoc")
+
+_HEADING_RE = re.compile(r"^(={1,6})\s+(.+?)\s*$")
+_ATTR_ENTRY_RE = re.compile(r"^:!?[A-Za-z0-9_-]+:(?:\s|$)")
+_BLOCK_MACRO_RE = re.compile(r"^\[(?:source|NOTE|TIP|WARNING|CAUTION|IMPORTANT|listing|example|quote|verse|sidebar|pass|abstract|partintro)[,\]]")
+
+
+def detect(lines: list[str]) -> bool:
+    """Return True when content has unambiguous AsciiDoc markers.
+
+    We require co-occurring signals to avoid false-positives:
+    - A ``= Document Title`` line (level-0 heading) plus at least one
+      attribute entry or block macro; OR
+    - A block macro (``[source,…]``, admonition) alone.
+    """
+    has_doc_title = False
+    has_section = False
+    has_attr = False
+    has_block = False
+    for line in lines:
+        s = line.rstrip()
+        if _BLOCK_MACRO_RE.match(s):
+            has_block = True
+        if _ATTR_ENTRY_RE.match(s):
+            has_attr = True
+        m = _HEADING_RE.match(s)
+        if m:
+            if len(m.group(1)) == 1:
+                has_doc_title = True
+            else:
+                has_section = True
+    if has_block:
+        return True
+    # Level-0 document title paired with attribute entries or section headings
+    if has_doc_title and (has_attr or has_section):
+        return True
+    return False
+
+
+def parse(text: str) -> Iterator[OutlineItem]:
+    lines = text.splitlines(keepends=True)
+    n = len(lines)
+
+    headings: list[tuple[int, int, str]] = []  # (0-based idx, level, sig)
+
+    for i, line in enumerate(lines):
+        stripped = line.rstrip("\r\n")
+        m = _HEADING_RE.match(stripped)
+        if m:
+            level = len(m.group(1))
+            sig = "=" * level + " " + m.group(2)
+            headings.append((i, level, sig))
+
+    if not headings:
+        # Fallback: first non-empty line spans the whole file
+        first_sig = next((l.strip() for l in lines if l.strip()), "")
+        if first_sig:
+            yield OutlineItem(start=1, count=n, signature=extract_summary(first_sig))
+        return
+
+    for idx, (line_idx, level, sig) in enumerate(headings):
+        end_line = n
+        for future_line_idx, future_level, _ in headings[idx + 1:]:
+            if future_level <= level:
+                end_line = future_line_idx
+                break
+        yield OutlineItem(start=line_idx + 1, count=end_line - line_idx, signature=sig)