outliner-cli 0.1.0__py3-none-any.whl

outliner/__init__.py

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

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/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/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)

outliner/parsers/c.py

@@ -0,0 +1,281 @@
+"""C/C++ outline parser (regex-based)."""
+
+import re
+from collections.abc import Iterator
+
+from outliner.types import OutlineItem
+from outliner.parsers.util import extract_signature, indent_level, seek_comment_start, seek_brace_end
+
+
+def _block_comment_set(lines: list[str]) -> set[int]:
+    """Return 0-based line indices that are inside a /* */ block comment.
+
+    The opening line (containing /*) is NOT included unless it is also
+    a continuation (i.e. the same line also contains text after the /*)
+    that carries no code — callers skip it based on the leading * check.
+    Subsequent lines until the matching */ are included.
+    """
+    inside = False
+    result: set[int] = set()
+    for i, raw in enumerate(lines):
+        if inside:
+            result.add(i)
+            if "*/" in raw:
+                inside = False
+        elif "/*" in raw:
+            pos = raw.index("/*")
+            if raw.find("*/", pos + 2) == -1:
+                inside = True  # comment continues beyond this line
+    return result
+
+SYNTAX = "c"
+EXTENSIONS = (".c", ".h", ".cpp", ".cc", ".cxx", ".hpp", ".hxx", ".hh")
+
+# ---------------------------------------------------------------------------
+# Detection
+# ---------------------------------------------------------------------------
+
+_INCLUDE_RE = re.compile(r"^\s*#\s*include\s*[<\"]")
+_DETECT_STRUCT_RE = re.compile(r"\b(?:struct|class|namespace|union|enum)\s+\w+")
+_DETECT_FUNC_RE = re.compile(r"\w+\s*\([^)\n]*\)\s*(?:const\s+)?[{;]")
+
+
+def detect(lines: list[str]) -> bool:
+    """Detect C/C++: requires #include AND a structural code marker."""
+    if not any(_INCLUDE_RE.match(l) for l in lines):
+        return False
+    text = "\n".join(lines)
+    return bool(_DETECT_STRUCT_RE.search(text) or _DETECT_FUNC_RE.search(text))
+
+
+# ---------------------------------------------------------------------------
+# Macro (#define)
+# ---------------------------------------------------------------------------
+
+_DEFINE_RE = re.compile(r"^\s*#\s*define\s+\w+")
+
+
+def _collect_define(lines: list[str], start: int) -> tuple[str, int]:
+    """Collect a #define, following backslash line continuations."""
+    parts = [lines[start].rstrip()]
+    i = start
+    while parts[-1].endswith("\\") and i + 1 < len(lines):
+        i += 1
+        parts.append(lines[i].rstrip())
+    sig = " ".join(p.rstrip("\\").strip() for p in parts)
+    sig = re.sub(r"\s+", " ", sig).strip()
+    return sig, i
+
+
+# ---------------------------------------------------------------------------
+# Template prefix
+# ---------------------------------------------------------------------------
+
+_TEMPLATE_RE = re.compile(r"^\s*template\s*<")
+
+
+def _collect_template_sig(lines: list[str], start: int) -> tuple[str, int]:
+    """Collect template<...> parameters, handling nested angle brackets."""
+    depth = 0
+    parts: list[str] = []
+    for i in range(start, min(start + 10, len(lines))):
+        raw = lines[i]
+        for ch in raw:
+            if ch == "<":
+                depth += 1
+            elif ch == ">":
+                depth -= 1
+        parts.append(raw.strip())
+        if depth <= 0:
+            break
+    return extract_signature(parts), i
+
+
+# ---------------------------------------------------------------------------
+# Type declarations (struct / class / union / enum / namespace)
+# ---------------------------------------------------------------------------
+
+# Matches 'struct Name', 'class Name', etc. but NOT 'struct Name varname'
+# Lookahead ensures after the name there is no other identifier (variable name).
+_TYPE_RE = re.compile(
+    r"^\s*"
+    r"(?:(?:static|inline|extern|virtual|explicit|constexpr|friend)\s+)*"
+    r"(?:typedef\s+)?"
+    r"(?:struct|class|union|enum(?:\s+class)?|namespace)\s+\w+"
+    r"\s*(?=[{;:<]|//|$)"  # followed by {, ;, :, <, //, or end-of-line
+)
+
+# ---------------------------------------------------------------------------
+# Function / method detection
+# ---------------------------------------------------------------------------
+
+_FLOW_STARTERS = frozenset({
+    "if", "else", "while", "for", "do", "switch", "case",
+    "return", "goto", "throw", "try", "catch",
+    "sizeof", "typeof", "alignof", "decltype",
+})
+
+_STMT_START_RE = re.compile(
+    r"^\s*(?:return|throw|break|continue|goto|delete\b|assert\b|static_assert\b)\b"
+)
+
+# Identifier (with optional ~) or operator overload, followed by (
+_FUNC_NAME_PAREN_RE = re.compile(
+    r"(~?\w+|operator\s*(?:\(\)|[+\-*/%^&|~!<>=,\[\]()\s]+?))\s*\("
+)
+
+
+def _is_func_line(raw: str) -> bool:
+    """Return True if line looks like a C/C++ function/method declaration."""
+    s = raw.strip()
+    # Skip comment lines, constructor-init-list and comma continuations
+    if not s or s[0] in ("*", ":", ",") or s.startswith("//") or s.startswith("/*"):
+        return False
+    if _STMT_START_RE.match(raw):
+        return False
+    for m in _FUNC_NAME_PAREN_RE.finditer(raw):
+        name = m.group(1).strip()
+        if name in _FLOW_STARTERS:
+            continue
+        prefix = raw[: m.start()].strip()
+        if not prefix:
+            continue  # no return type — bare call or constructor without qualifier
+        # Exclude: assignment (x = func(...)) and member access (p->func(...))
+        if "=" in prefix or "->" in prefix:
+            continue
+        # Exclude: prefix contains a comment → tail of a statement line
+        if "//" in prefix:
+            continue
+        # Exclude: nested call — prefix has unmatched open paren
+        if prefix.count("(") > prefix.count(")"):
+            continue
+        # Exclude: bare namespace/template qualifier with no return type (e.g. "std::", "Foo<T>::")
+        if prefix.endswith("::") and " " not in prefix:
+            continue
+        # Exclude: member access via . or closing bracket
+        if re.search(r"[).\]]\s*$", prefix):
+            continue
+        first_word = re.split(r"\W+", prefix.lstrip())[0] if prefix.lstrip() else ""
+        if first_word in _FLOW_STARTERS:
+            continue
+        return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Signature collection
+# ---------------------------------------------------------------------------
+
+
+def _collect_sig(lines: list[str], start: int) -> tuple[str, int, bool]:
+    """Collect a C/C++ function or type signature spanning multiple lines.
+
+    Tracks parenthesis depth; stops when depth returns to 0 and line ends with
+    { (has body) or ; (declaration only).
+    Returns (signature, last_sig_line_0based, has_body).
+    """
+    depth = 0
+    parts: list[str] = []
+    ind = " " * indent_level(lines[start])
+    has_body = False
+
+    for i in range(start, min(start + 30, len(lines))):
+        raw = lines[i]
+        for ch in raw:
+            if ch == "(":
+                depth += 1
+            elif ch == ")":
+                depth -= 1
+        parts.append(raw.strip())
+        if depth <= 0:
+            bd = raw.count("{") - raw.count("}")
+            if bd > 0 or (bd == 0 and raw.rstrip().endswith("}")):
+                has_body = True
+                break
+            if raw.rstrip().endswith(";"):
+                break
+
+    sig = ind + extract_signature(parts, strip="{;")
+    # For one-liner bodies the inline body may remain; truncate at first {
+    if has_body:
+        brace = sig.find("{")
+        if brace != -1:
+            sig = sig[:brace].rstrip()
+    # Strip constructor init list: ): ... before end of sig
+    sig = re.sub(r"\)\s*:(?!:)[^{;]*$", ")", sig).rstrip()
+    return sig, i, has_body
+
+
+def parse(text: str) -> Iterator[OutlineItem]:
+    _is_comment = lambda _, s: s[:1] in '/*'
+    lines = text.splitlines()
+    n = len(lines)
+    block_comments = _block_comment_set(lines)
+    i = 0
+
+    while i < n:
+        line = lines[i]
+
+        # Skip lines inside /* */ block comments, blank lines, and line comments
+        s = line.strip()
+        if i in block_comments or not s or s[0] == "*" or s.startswith("//"):
+            i += 1
+            continue
+
+        # --- #define macros ---
+        if _DEFINE_RE.match(line):
+            sig, sig_end = _collect_define(lines, i)
+            start = seek_comment_start(lines, i, _is_comment)
+            yield OutlineItem(start=start + 1, count=sig_end - start + 1, signature=sig)
+            i = sig_end + 1
+            continue
+
+        # Skip other preprocessor directives (#if, #ifdef, #include, #pragma, etc.)
+        if s.startswith("#"):
+            i += 1
+            continue
+
+        # --- template<...> + following declaration ---
+        if _TEMPLATE_RE.match(line):
+            tmpl_sig, tmpl_end = _collect_template_sig(lines, i)
+            start = seek_comment_start(lines, i, _is_comment)
+            # Find the declaration following the template params (skip blanks and preprocessor)
+            j = tmpl_end + 1
+            while j < n and (not lines[j].strip() or lines[j].strip().startswith("#")):
+                j += 1
+            if j < n and (_TYPE_RE.match(lines[j]) or _is_func_line(lines[j])):
+                is_type_decl = bool(_TYPE_RE.match(lines[j]))
+                decl_sig, decl_end, has_body = _collect_sig(lines, j)
+                full_sig = tmpl_sig + " " + decl_sig.strip()
+                end = seek_brace_end(lines, decl_end) if has_body else decl_end + 1
+                yield OutlineItem(start=start + 1, count=end - start, signature=full_sig)
+                if has_body and not is_type_decl:
+                    i = end  # skip function body entirely
+                else:
+                    i = decl_end + 1  # advance into type body so members are parsed
+            else:
+                i = tmpl_end + 1
+            continue
+
+        # --- type declarations (struct/class/union/enum/namespace) ---
+        if _TYPE_RE.match(line):
+            sig, sig_end, has_body = _collect_sig(lines, i)
+            start = seek_comment_start(lines, i, _is_comment)
+            end = seek_brace_end(lines, sig_end) if has_body else sig_end + 1
+            yield OutlineItem(start=start + 1, count=end - start, signature=sig)
+            i = sig_end + 1  # advance into body to parse members
+            continue
+
+        # --- function / method declarations and definitions ---
+        if _is_func_line(line):
+            sig, sig_end, has_body = _collect_sig(lines, i)
+            start = seek_comment_start(lines, i, _is_comment)
+            end = seek_brace_end(lines, sig_end) if has_body else sig_end + 1
+            yield OutlineItem(start=start + 1, count=end - start, signature=sig)
+            if has_body:
+                i = end  # skip body to avoid matching statements inside
+            else:
+                i = sig_end + 1
+            continue
+
+        i += 1