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

{outliner_cli-0.2.0 → outliner_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: outliner-cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: Print the structural outline of source files for LLM navigation
 Author: Per Cederberg
 License-Expression: MIT
@@ -13,7 +13,7 @@ Dynamic: license-file
 
 # outliner
 
-Print the structural outline of source files — useful declarations and callable
+Print the structural outline of source files — declarations and callable
 landmarks with line ranges — so an LLM agent (or human) can navigate a file
 without reading it whole.
 
@@ -23,16 +23,20 @@ without reading it whole.
 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                           |
-| `-w, --width COLS`  | Truncate output lines to COLS (`0`=unlimited, `auto`=terminal, default=`120`) |
+| Option               | Description                                          |
+| -------------------- | ---------------------------------------------------- |
+| `-g, --grep EXPR`    | Only show items whose signature matches EXPR         |
+| `-s, --syntax LANG`  | Override syntax auto-detection when ambiguous        |
+| `-t, --type LANG`    | Only include files of this language (repeatable)     |
+| `-w, --width COLS`   | Truncate lines (`0`=off, `auto`=fit, default `120`)  |
+| `-x, --exclude GLOB` | Exclude files from directory walks (gitignore-style) |
 
 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).
+Use `-` to read stdin explicitly. Directory walks honor `.gitignore` and skip
+hidden directories; all other files are listed, with binary and unrecognized
+files shown as one-line `binary file` / `unsupported file` summaries. `--syntax`
+is only needed when content auto-detection cannot identify the language (e.g. an
+ambiguous extensionless script piped on stdin).
 
 ## Output
 
@@ -46,7 +50,7 @@ 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
+- `signature` — first non-comment line of a declaration; multi-line signatures
   are merged into one line; lines longer than the output width are truncated
   with `...`
 
@@ -57,7 +61,7 @@ methods) and native-format indentation in the signature (indented for code,
 ## Installation
 
 ```sh
-pip install outliner
+pip install outliner-cli
 ```
 
 ## Running
@@ -79,13 +83,13 @@ uv run pytest
 
 ## Supported Languages
 
-AsciiDoc, C/C++, C#, Clojure, Go, HTML, Java, JavaScript/TypeScript, Markdown,
-Org-mode, Perl, PHP, Python, reStructuredText, Ruby, Rust, Scala, Shell, Swift,
-and Zig.
+AsciiDoc, C/C++, C#, Clojure, Go, HTML, Java, JavaScript/TypeScript (incl.
+Svelte, Vue, and Astro components), JSON/NDJSON, Markdown, Org-mode, Perl, PHP,
+Python, reStructuredText, Ruby, Rust, Scala, Shell, Swift, XML, and Zig.
 
 ## Example Use Cases
 
-**Structural overview** — Run on a directory to see all declarations across many
+**Structural overview** — Run on a directory to see declarations across all
 files before reading anything:
 
 ```
@@ -132,3 +136,32 @@ $ uvx outliner-cli --grep PaymentMethod src/
  14,12  def charge(method: PaymentMethod, amount: Decimal) -> Receipt
  88,4   def validate(m: PaymentMethod) -> bool
 ```
+
+**Inspect a dataset without opening it** — JSON/NDJSON files show a schema
+overview with file size, record count, data types, optionality, and truncated
+sample values:
+
+```
+$ uvx outliner-cli titanic.json
+$             163.9 KB · json · array[891]
+.Age          float|int? -- 22
+.Cabin        str? -- "C85"
+.Embarked     str? -- "S"
+.Fare         float|int -- 7.25
+.Name         str -- "Braund, Mr. Owen Harris"
+.Survived     int -- 0
+```
+
+XML files show an indented structural outline with XML-native node kinds:
+
+```
+$ uvx outliner-cli pubmed26n0001.xml
+/                                195.5 MB · xml · sampled 204K elems
+<PubmedArticleSet>               elem
+  <PubmedArticle>                elem+
+    <MedlineCitation>            elem
+      @Status                    attr -- "MEDLINE"
+      <Article>                  elem
+        <ArticleTitle>           text -- "Formate assay in body fluids..."
+        <Abstract>               elem?
+```

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

@@ -1,6 +1,6 @@
 # outliner
 
-Print the structural outline of source files — useful declarations and callable
+Print the structural outline of source files — declarations and callable
 landmarks with line ranges — so an LLM agent (or human) can navigate a file
 without reading it whole.
 
@@ -10,16 +10,20 @@ without reading it whole.
 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                           |
-| `-w, --width COLS`  | Truncate output lines to COLS (`0`=unlimited, `auto`=terminal, default=`120`) |
+| Option               | Description                                          |
+| -------------------- | ---------------------------------------------------- |
+| `-g, --grep EXPR`    | Only show items whose signature matches EXPR         |
+| `-s, --syntax LANG`  | Override syntax auto-detection when ambiguous        |
+| `-t, --type LANG`    | Only include files of this language (repeatable)     |
+| `-w, --width COLS`   | Truncate lines (`0`=off, `auto`=fit, default `120`)  |
+| `-x, --exclude GLOB` | Exclude files from directory walks (gitignore-style) |
 
 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).
+Use `-` to read stdin explicitly. Directory walks honor `.gitignore` and skip
+hidden directories; all other files are listed, with binary and unrecognized
+files shown as one-line `binary file` / `unsupported file` summaries. `--syntax`
+is only needed when content auto-detection cannot identify the language (e.g. an
+ambiguous extensionless script piped on stdin).
 
 ## Output
 
@@ -33,7 +37,7 @@ 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
+- `signature` — first non-comment line of a declaration; multi-line signatures
   are merged into one line; lines longer than the output width are truncated
   with `...`
 
@@ -44,7 +48,7 @@ methods) and native-format indentation in the signature (indented for code,
 ## Installation
 
 ```sh
-pip install outliner
+pip install outliner-cli
 ```
 
 ## Running
@@ -66,13 +70,13 @@ uv run pytest
 
 ## Supported Languages
 
-AsciiDoc, C/C++, C#, Clojure, Go, HTML, Java, JavaScript/TypeScript, Markdown,
-Org-mode, Perl, PHP, Python, reStructuredText, Ruby, Rust, Scala, Shell, Swift,
-and Zig.
+AsciiDoc, C/C++, C#, Clojure, Go, HTML, Java, JavaScript/TypeScript (incl.
+Svelte, Vue, and Astro components), JSON/NDJSON, Markdown, Org-mode, Perl, PHP,
+Python, reStructuredText, Ruby, Rust, Scala, Shell, Swift, XML, and Zig.
 
 ## Example Use Cases
 
-**Structural overview** — Run on a directory to see all declarations across many
+**Structural overview** — Run on a directory to see declarations across all
 files before reading anything:
 
 ```
@@ -119,3 +123,32 @@ $ uvx outliner-cli --grep PaymentMethod src/
  14,12  def charge(method: PaymentMethod, amount: Decimal) -> Receipt
  88,4   def validate(m: PaymentMethod) -> bool
 ```
+
+**Inspect a dataset without opening it** — JSON/NDJSON files show a schema
+overview with file size, record count, data types, optionality, and truncated
+sample values:
+
+```
+$ uvx outliner-cli titanic.json
+$             163.9 KB · json · array[891]
+.Age          float|int? -- 22
+.Cabin        str? -- "C85"
+.Embarked     str? -- "S"
+.Fare         float|int -- 7.25
+.Name         str -- "Braund, Mr. Owen Harris"
+.Survived     int -- 0
+```
+
+XML files show an indented structural outline with XML-native node kinds:
+
+```
+$ uvx outliner-cli pubmed26n0001.xml
+/                                195.5 MB · xml · sampled 204K elems
+<PubmedArticleSet>               elem
+  <PubmedArticle>                elem+
+    <MedlineCitation>            elem
+      @Status                    attr -- "MEDLINE"
+      <Article>                  elem
+        <ArticleTitle>           text -- "Formate assay in body fluids..."
+        <Abstract>               elem?
+```

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "outliner-cli"
-version = "0.2.0"
+version = "0.4.0"
 description = "Print the structural outline of source files for LLM navigation"
 authors = [{name = "Per Cederberg"}]
 license = "MIT"

{outliner_cli-0.2.0 → outliner_cli-0.4.0}/src/outliner/cli.py

@@ -8,8 +8,12 @@ import shutil
 import sys
 
 from outliner.parsers import NAMES, EXTENSIONS, detect, outline, syntax
+from outliner.parsers.util import format_count, format_size
 from outliner.types import OutlineItem
 
+_TEXT_CONTROLS = "\n\r\t\f\b"
+_BINARY_THRESHOLD = 0.05
+
 
 def die(msg: str, code: int = 2) -> None:
     print(f"outliner: {msg}", file=sys.stderr)
@@ -53,22 +57,27 @@ def _is_ignored(name: str, root: str, gi: dict[str, list[str]], is_dir: bool) ->
     return False
 
 
-def _expand_sources(sources: list[str], types: set[str] | None = None) -> list[str]:
+def _expand_sources(
+    sources: list[str],
+    types: set[str] | None = None,
+    excludes: list[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]] = {}
+        # CLI excludes behave like a .gitignore in the walk root
+        gi: dict[str, list[str]] = {os.path.normpath(src): list(excludes)} if excludes else {}
         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))
+                gi[root] = gi.get(root, []) + pats
+            dirs[:] = sorted(d for d in dirs
+                             if not d.startswith(".") and 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):
+                wanted = not types or guess_syntax(name) in types
+                if wanted and not _is_ignored(name, root, gi, False):
                     result.append(os.path.join(root, name))
     return result
 
@@ -78,9 +87,55 @@ def _format_items(items: list[OutlineItem], grep: re.Pattern | None, line_width:
         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]
+    fmt_width = max(it.fmt_width for it in items)
+    fmt_width = max(fmt_width, 3)
+    return [it.format(fmt_width, line_width) for it in items]
+
+
+def _looks_binary(head: str) -> bool:
+    if "\0" in head:
+        return True
+    if head:
+        controls = sum(1 for ch in head if ord(ch) < 32 and ch not in _TEXT_CONTROLS)
+        replaced = head.count("\ufffd")
+        return (controls + replaced) / len(head) > _BINARY_THRESHOLD
+    return False
+
+
+def _unsupported_items(size: int, line_count: int) -> list[OutlineItem]:
+    plural = "s" if line_count != 1 else ""
+    sig = f"{format_size(size)} \u00b7 {format_count(line_count)} line{plural}"
+    return [OutlineItem(locator="unsupported file", signature=sig)]
+
+
+def _outline_source(src: str, selected: str | None) -> tuple[list[OutlineItem] | None, str]:
+    if src == "-":
+        if selected:
+            return outline(selected, sys.stdin), selected
+        text = sys.stdin.read().removeprefix("\ufeff")
+        match = detect(text)
+        if match:
+            return outline(match, text), match
+        if not text.strip():
+            return [], "unsupported"
+        return _unsupported_items(len(text), len(text.splitlines())), "unsupported"
+
+    with open(src, encoding="utf-8-sig", errors="replace") as fh:
+        head = fh.read(4096)
+        if _looks_binary(head):
+            size = format_size(os.path.getsize(src))
+            return [OutlineItem(locator="binary file", signature=size)], "binary"
+        match = selected or guess_syntax(src) or detect(head)
+        if match:
+            fh.seek(0)
+            return outline(match, fh), match
+        line_count, tail = head.count("\n"), head
+        while chunk := fh.read(1 << 20):
+            line_count += chunk.count("\n")
+            tail = chunk
+        if tail and not tail.endswith("\n"):
+            line_count += 1
+        return _unsupported_items(os.path.getsize(src), line_count), "unsupported"
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -98,6 +153,8 @@ def main(argv: list[str] | None = None) -> int:
                     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)")
+    ap.add_argument("-x", "--exclude", action="append", metavar="PATTERN",
+                    help="Exclude matching files from directory walks, like .gitignore (repeatable)")
     args = ap.parse_args(argv)
 
     grep_re: re.Pattern | None = None
@@ -137,38 +194,18 @@ def main(argv: list[str] | None = None) -> int:
     if sources == ["-"] and sys.stdin.isatty():
         ap.print_help()
         return 0
-    sources = _expand_sources(sources, types)
+    sources = _expand_sources(sources, types, args.exclude)
     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()
+            items, _ = _outline_source(src, args.syntax)
         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:

outliner_cli-0.4.0/src/outliner/parsers/__init__.py

@@ -0,0 +1,65 @@
+import io
+import re
+import types
+from typing import TextIO
+
+from ..types import OutlineItem
+from . import (
+    python, scala, go, java, rust, swift, c, ruby, php, shell, javascript,
+    csharp, perl, zig, clojure, html, asciidoc, orgmode, rst, json, xml,
+    markdown,
+)
+
+_MODULES = {
+    mod.SYNTAX: mod
+    for mod in globals().values() if (
+        isinstance(mod, types.ModuleType)
+        and mod.__name__.startswith(f"{__name__}.")
+        and hasattr(mod, "SYNTAX")
+        and hasattr(mod, "EXTENSIONS")
+    )
+}
+NAMES = sorted(_MODULES)
+EXTENSIONS = {ext: syntax for syntax, mod in _MODULES.items() 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 syntax(name: str) -> str | None:
+    if name in _MODULES:
+        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.values():
+        if mod.detect(lines):
+            return mod.SYNTAX
+    return None
+
+
+def outline(syntax: str, content: str | TextIO) -> list[OutlineItem] | None:
+    mod = _MODULES.get(syntax)
+    if not mod:
+        return None
+    elif hasattr(mod, "read"):
+        fh = io.StringIO(content) if isinstance(content, str) else content
+        return list(mod.read(fh))
+    else:
+        text = content.read() if hasattr(content, "read") else content
+        return _outline_text(mod, text)
+
+
+def _outline_text(mod, content: str) -> list[OutlineItem]:
+    m = _FRONTMATTER_RE.match(content) if getattr(mod, "STRIP_FRONTMATTER", True) else None
+    if not m:
+        return list(mod.parse(content))
+    offset = m.group(0).count('\n')
+    return [OutlineItem(start=it.start + offset, count=it.count, signature=it.signature)
+            for it in mod.parse(content[m.end():])]