markback 0.1.2__tar.gz → 0.1.5__tar.gz

markback-0.1.5/.claude/settings.local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python -m pytest:*)",
+      "Bash(npm test:*)",
+      "Bash(npm install)",
+      "Bash(npm run build:*)",
+      "Bash(echo:*)",
+      "Bash(python -m markback lint:*)",
+      "Bash(python:*)",
+      "Bash(python3 -m pytest:*)",
+      "Bash(pip3 install:*)",
+      "Bash(.venv/bin/python -m pytest:*)",
+      "Bash(chmod:*)",
+      "Bash(grep:*)",
+      "Bash(wc:*)",
+      "Bash(ls:*)",
+      "Bash(pip install:*)",
+      "Bash(PYTHONPATH=/src/markback EDITOR=cat python3:*)",
+      "Bash(PYTHONPATH=/src/markback python3:*)"
+    ]
+  }
+}

{markback-0.1.2 → markback-0.1.5}/.ishipped/card.md

@@ -2,6 +2,7 @@
 title: "MarkBack"
 summary: "Human-writable format for pairing content with labels and feedback."
 shipped: 2026-01-04
+theme: forest
 tags: [data-annotation, machine-learning, cli, python, typescript]
 links:
   - label: "markback.org"

{markback-0.1.2 → markback-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markback
-Version: 0.1.2
+Version: 0.1.5
 Summary: A compact, human-writable format for storing content paired with feedback/labels
 Project-URL: Homepage, https://github.com/dandriscoll/markback
 Project-URL: Repository, https://github.com/dandriscoll/markback
@@ -95,10 +95,17 @@ if result.has_errors:
 
 ## CLI Usage
 
+The CLI is available via two commands:
+- `markback` - Full command name
+- `mb` - Convenient shorthand (works on all platforms including Windows)
+
+Both commands are functionally identical. Examples below use `markback`, but you can substitute `mb` anywhere.
+
 ### Initialize configuration
 
 ```bash
 markback init
+# or: mb init
 ```
 
 Creates a `.env` file with all configuration options.

{markback-0.1.2 → markback-0.1.5}/README.md

@@ -60,10 +60,17 @@ if result.has_errors:
 
 ## CLI Usage
 
+The CLI is available via two commands:
+- `markback` - Full command name
+- `mb` - Convenient shorthand (works on all platforms including Windows)
+
+Both commands are functionally identical. Examples below use `markback`, but you can substitute `mb` anywhere.
+
 ### Initialize configuration
 
 ```bash
 markback init
+# or: mb init
 ```
 
 Creates a `.env` file with all configuration options.

{markback-0.1.2 → markback-0.1.5}/SPEC.md

@@ -27,6 +27,7 @@ A MarkBack **record** is the fundamental unit. Every record has:
 | `content` | Yes* | The content being labeled (inline or referenced) |
 | `feedback` | Yes | Text after the `<<<` delimiter (always one line) |
 | `uri` | No | Unique identifier for the item |
+| `by` | No | Freeform identifier for who provided the feedback |
 | `source` | No | Reference to external content (when content is not inline) |
 | `prior` | No | Reference to an item that precedes the source (e.g., a prompt that generated the content) |
 
@@ -66,6 +67,7 @@ Header lines appear at the start of a record and begin with `@`. They define met
 
 ```
 @uri <uri-value>
+@by <freeform-text>
 @source <path-or-uri>
 @prior <path-or-uri>
 ```
@@ -95,7 +97,23 @@ Defines the unique identifier for this record.
 
 **Validation:** URI MUST be valid per RFC 3986. Parsers MUST reject malformed URIs as errors.
 
-#### 3.1.2 `@source` Header
+#### 3.1.2 `@by` Header
+
+Identifies who provided the feedback. The value is freeform text.
+
+```
+@by dan@example.com
+@by Dan Driscoll
+@by reviewer-42
+```
+
+**Rules:**
+- Value is freeform text extending to end of line (trailing whitespace trimmed)
+- Can contain any characters including spaces, special characters, etc.
+- Commonly used for email addresses, usernames, or full names
+- Optional - records without `@by` are valid
+
+#### 3.1.3 `@source` Header
 
 References external content instead of inline content.
 
@@ -111,7 +129,7 @@ References external content instead of inline content.
 - When `@source` is present, inline content MUST be empty (or contain only whitespace)
 - Parsers MUST verify referenced files exist (warning if missing)
 
-#### 3.1.3 `@prior` Header
+#### 3.1.4 `@prior` Header
 
 References an item that precedes the source material. For example, if the source is an image generated by an LLM, the prior could be the prompt that was used to create it.
 
@@ -127,26 +145,36 @@ References an item that precedes the source material. For example, if the source
 - `@prior` does not affect content handling (inline content or `@source` rules still apply)
 - Parsers SHOULD verify referenced files exist (warning if missing)
 
-#### 3.1.4 Line Range Specification
+#### 3.1.5 Line and Character Range Specification
 
-Both `@source` and `@prior` headers support optional line range specifications using colon notation. This allows referencing specific lines within a file.
+Both `@source` and `@prior` headers support optional line and character range specifications using colon notation. This allows referencing specific positions within a file.
 
-**Syntax:** `<path-or-uri>:<start>` or `<path-or-uri>:<start>-<end>`
+**Syntax:**
+- Line only: `<path-or-uri>:<line>` or `<path-or-uri>:<start-line>-<end-line>`
+- With columns: `<path-or-uri>:<line>:<col>` or `<path-or-uri>:<start-line>:<start-col>-<end-line>:<end-col>`
 
 ```
 @source ./code.py:42
 @source ./code.py:42-50
+@source ./code.py:42:10
+@source ./code.py:42:10-42:25
+@source ./code.py:10:5-15:20
 @prior ./prompts/template.txt:1-20
 @source https://example.com/file.txt:100-150
 ```
 
 **Rules:**
-- Line numbers are 1-indexed (first line is line 1)
+- Line and column numbers are 1-indexed (first line/column is 1)
 - Single line: `:N` references line N only
 - Line range: `:N-M` references lines N through M (inclusive)
-- End line must be greater than or equal to start line (E011 error otherwise)
-- Line ranges are informational metadata; parsers do not validate that referenced lines exist in the file
+- Single position: `:N:C` references line N, column C
+- Character range: `:N:C-M:D` references from line N column C to line M column D (inclusive)
+- End position must be greater than or equal to start position (E011 error otherwise)
+  - If on same line: end column must be >= start column
+  - If on different lines: end line must be >= start line
+- Ranges are informational metadata; parsers do not validate that referenced positions exist in the file
 - Windows drive letters (e.g., `C:\path`) are not confused with line ranges because scheme detection requires length > 1
+- Column specification is optional; you can specify `:10:5-20` (start with column, end without)
 
 ### 3.2 Content Block
 
@@ -481,7 +509,7 @@ Canonical form ensures consistent output for comparison and version control.
 ### 5.2 Canonicalization Rules
 
 1. **Line endings:** Normalize to `\n` (LF)
-2. **Header order:** `@uri` before `@prior` before `@source` before unknown headers (alphabetical)
+2. **Header order:** `@uri` before `@by` before `@prior` before `@source` before unknown headers (alphabetical)
 3. **Header spacing:** Exactly one space after keyword
 4. **Trailing whitespace:** Remove from all lines
 5. **Content whitespace:** Preserve internal whitespace; trim leading/trailing blank lines
@@ -678,7 +706,42 @@ Spring whispers goodbye.
 <<< creative; follows haiku structure; quality=excellent
 ```
 
-### 8.5 Single-File Example
+### 8.5 Record with Attribution
+
+```
+@uri local:review-001
+@by dan@example.com
+
+This code needs better error handling.
+<<< actionable; priority=high
+```
+
+Or with a full name:
+```
+@uri local:review-002
+@by Dan Driscoll
+@source ./src/app.py
+<<< approved; good code quality
+```
+
+### 8.6 Character-Level References
+
+Reference a specific position in a file:
+```
+@source ./code.py:42:10 <<< potential bug at this position
+```
+
+Reference a character range on a single line:
+```
+@source ./code.py:42:10-42:25 <<< consider renaming this variable
+```
+
+Reference a multi-line character range:
+```
+@source ./code.py:10:5-15:20 <<< this function needs refactoring
+```
+
+### 8.7 Single-File Example
 
 **File:** `question.mb`
 ```
@@ -688,7 +751,7 @@ Explain quantum entanglement in simple terms.
 <<< quality=excellent; accuracy=high; clarity=good
 ```
 
-### 8.6 Label List Example (Compact Format)
+### 8.8 Label List Example (Compact Format)
 
 **File:** `image-annotations.mb`
 ```
@@ -720,7 +783,7 @@ Explain quantum entanglement in simple terms.
 @source ./batch1/item3.txt <<< positive; excellent clarity
 ```
 
-### 8.7 Multi-Record Example (Mixed Freeform and Structured)
+### 8.9 Multi-Record Example (Mixed Freeform and Structured)
 
 **File:** `training-data.mb`
 ```
@@ -751,7 +814,7 @@ Please write a formal letter requesting a meeting.
 @source ./audio/sample-005.wav <<< transcription="Hello world"; quality=clear; language=en
 ```
 
-### 8.8 Paired-File Example
+### 8.10 Paired-File Example
 
 **Content file:** `essay.txt`
 ```
@@ -767,7 +830,7 @@ agriculture, manufacturing, mining, and transport.
 <<< good; grade=B+; well structured but needs more specific examples
 ```
 
-### 8.9 Freeform Feedback Examples
+### 8.11 Freeform Feedback Examples
 
 Various styles of freeform feedback:
 
@@ -790,7 +853,7 @@ Explain machine learning to a child.
 <<< needs work; the explanation assumes too much prior knowledge
 ```
 
-### 8.10 Complex Structured Feedback (JSON)
+### 8.12 Complex Structured Feedback (JSON)
 
 ```
 @uri local:complex-example
@@ -799,7 +862,7 @@ Multi-attribute content with special characters.
 <<< json:{"rating":4.5,"tags":["important","review"],"notes":"Contains \"quoted\" text and; semicolons","scores":{"accuracy":0.9,"relevance":0.85}}
 ```
 
-### 8.11 Image with MarkBack Sidecar
+### 8.13 Image with MarkBack Sidecar
 
 **Content file:** `diagram.png` (binary)
 
@@ -882,13 +945,15 @@ feedback        = "<<<" SP feedback-content LF
 feedback-content = *VCHAR             ; no LF allowed
 
 ; Compact record (single line, external source only)
-compact-record  = [uri-line] source-feedback-line
+compact-record  = [uri-line] [by-line] [prior-line] source-feedback-line
 compact-list    = compact-record *(1*blank-line compact-record)
 uri-line        = "@uri" SP value LF
+by-line         = "@by" SP value LF
+prior-line      = "@prior" SP path-with-range LF
 source-feedback-line = "@source" SP path-with-range SP "<<<" SP feedback-content LF
-path-with-range = path [line-range]   ; path with optional line range
-path            = 1*VCHAR             ; ends at space before <<< or line-range
-line-range      = ":" 1*DIGIT ["-" 1*DIGIT]
+path-with-range = path [position-range]   ; path with optional position range
+path            = 1*VCHAR             ; ends at space before <<< or position-range
+position-range  = ":" 1*DIGIT [":" 1*DIGIT] ["-" 1*DIGIT [":" 1*DIGIT]]
 
 LOWER           = %x61-7A  ; a-z
 SP              = %x20     ; space

markback-0.1.5/markback/cli.py

@@ -0,0 +1,122 @@
+"""MarkBack command-line interface."""
+
+import glob
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from .writer import write_file
+
+err_console = Console(stderr=True)
+
+
+def get_mb_path(target: Path) -> Path:
+    """Get the .mb file path for a target file."""
+    return target.with_suffix(target.suffix + ".mb")
+
+
+def get_feedback_path(directory: Path) -> Path:
+    """Get a non-colliding feedback.mb path in the given directory."""
+    candidate = directory / "feedback.mb"
+    if not candidate.exists():
+        return candidate
+    counter = 1
+    while True:
+        candidate = directory / f"feedback-{counter}.mb"
+        if not candidate.exists():
+            return candidate
+        counter += 1
+
+
+def collect_glob(pattern: str) -> None:
+    """Expand a glob pattern and write all matches into a single .mb file."""
+    from .types import Record, SourceRef
+
+    matches = sorted(glob.glob(pattern))
+    if not matches:
+        err_console.print(f"[red]No files match pattern: {pattern}[/red]")
+        raise typer.Exit(1)
+
+    records = [Record(source=SourceRef(f), feedback="") for f in matches]
+
+    # Determine output directory from the pattern's parent, defaulting to cwd
+    pattern_parent = Path(pattern).parent
+    output_dir = pattern_parent if pattern_parent != Path("") else Path(".")
+    output_path = get_feedback_path(output_dir)
+
+    write_file(output_path, records)
+    err_console.print(f"Created {output_path} with {len(records)} source(s)")
+    open_editor(output_path)
+
+
+def open_editor(path: Path) -> None:
+    """Open the file in the user's editor."""
+    editor = os.environ.get("EDITOR") or os.environ.get("VISUAL")
+
+    if editor:
+        subprocess.run([editor, str(path)])
+    elif sys.platform == "win32":
+        os.startfile(path)
+    elif sys.platform == "darwin":
+        subprocess.run(["open", str(path)])
+    else:
+        # Try xdg-open first, then fall back to common editors
+        if shutil.which("xdg-open"):
+            result = subprocess.run(["xdg-open", str(path)], capture_output=True)
+            if result.returncode == 0:
+                return
+        for fallback in ("nano", "vi"):
+            if shutil.which(fallback):
+                subprocess.run([fallback, str(path)])
+                return
+        err_console.print(
+            f"[red]No editor found. Set the EDITOR environment variable, e.g.:[/red]\n"
+            f"  export EDITOR=nano"
+        )
+        raise typer.Exit(1)
+
+
+def main(
+    target: Annotated[
+        str,
+        typer.Argument(help="Target file or glob pattern to manage feedback for"),
+    ],
+):
+    """MarkBack: Create or view feedback for a target file."""
+    # Check if target is a glob pattern
+    if any(c in target for c in ('*', '?', '[')):
+        collect_glob(target)
+        return
+
+    target = Path(target)
+    mb_path = get_mb_path(target)
+
+    if not mb_path.exists():
+        # Create new .mb file
+        if not target.exists():
+            err_console.print(f"[red]Target file not found: {target}[/red]")
+            raise typer.Exit(1)
+
+        from .types import Record
+        record = Record(
+            source=target,
+            feedback="",
+        )
+        write_file(mb_path, [record])
+
+    open_editor(mb_path)
+
+
+def cli():
+    """Entry point for the CLI."""
+    typer.run(main)
+
+
+if __name__ == "__main__":
+    cli()

{markback-0.1.2 → markback-0.1.5}/markback/linter.py

@@ -137,36 +137,61 @@ def lint_prior_exists(
     return diagnostics
 
 
+def _is_position_invalid(source_ref) -> tuple[bool, str]:
+    """Check if a SourceRef has an invalid position range.
+
+    Returns (is_invalid, error_message).
+    Position is invalid if:
+    - end_line < start_line
+    - end_line == start_line and end_column < start_column
+    """
+    if source_ref.start_line is None or source_ref.end_line is None:
+        return False, ""
+
+    if source_ref.end_line < source_ref.start_line:
+        return True, f"end line {source_ref.end_line} is less than start line {source_ref.start_line}"
+
+    if source_ref.end_line == source_ref.start_line:
+        if (source_ref.start_column is not None and
+            source_ref.end_column is not None and
+            source_ref.end_column < source_ref.start_column):
+            return True, f"end column {source_ref.end_column} is less than start column {source_ref.start_column} on line {source_ref.start_line}"
+
+    return False, ""
+
+
 def lint_line_range(
     record: Record,
     record_idx: int,
 ) -> list[Diagnostic]:
-    """Check if line ranges are valid (end >= start)."""
+    """Check if line/character ranges are valid (end position >= start position)."""
     diagnostics: list[Diagnostic] = []
 
-    # Check @source line range
+    # Check @source range
     if record.source and record.source.start_line is not None:
-        if record.source.end_line is not None and record.source.end_line < record.source.start_line:
+        is_invalid, error_msg = _is_position_invalid(record.source)
+        if is_invalid:
             diagnostics.append(Diagnostic(
                 file=record._source_file,
                 line=record._start_line,
                 column=None,
                 severity=Severity.ERROR,
                 code=ErrorCode.E011,
-                message=f"Invalid line range in @source: end line {record.source.end_line} is less than start line {record.source.start_line}",
+                message=f"Invalid range in @source: {error_msg}",
                 record_index=record_idx,
             ))
 
-    # Check @prior line range
+    # Check @prior range
     if record.prior and record.prior.start_line is not None:
-        if record.prior.end_line is not None and record.prior.end_line < record.prior.start_line:
+        is_invalid, error_msg = _is_position_invalid(record.prior)
+        if is_invalid:
             diagnostics.append(Diagnostic(
                 file=record._source_file,
                 line=record._start_line,
                 column=None,
                 severity=Severity.ERROR,
                 code=ErrorCode.E011,
-                message=f"Invalid line range in @prior: end line {record.prior.end_line} is less than start line {record.prior.start_line}",
+                message=f"Invalid range in @prior: {error_msg}",
                 record_index=record_idx,
             ))
 

{markback-0.1.2 → markback-0.1.5}/markback/parser.py

@@ -17,7 +17,7 @@ from .types import (
 
 
 # Known header keywords
-KNOWN_HEADERS = {"uri", "source", "prior"}
+KNOWN_HEADERS = {"uri", "by", "source", "prior"}
 
 # Patterns
 HEADER_PATTERN = re.compile(r"^@([a-z]+)\s+(.+)$")
@@ -145,6 +145,7 @@ def parse_string(
         nonlocal pending_uri, in_content, had_blank_line
 
         uri = current_headers.get("uri") or pending_uri
+        by = current_headers.get("by")
         source_str = current_headers.get("source")
         source = SourceRef(source_str) if source_str else None
         prior_str = current_headers.get("prior")
@@ -164,6 +165,7 @@ def parse_string(
         record = Record(
             feedback=feedback,
             uri=uri,
+            by=by,
             source=source,
             prior=prior,
             content=content,
@@ -242,14 +244,16 @@ def parse_string(
                     line_num,
                 )
 
-            # Use any pending @uri from previous line and @prior if present
+            # Use any pending @uri from previous line and @by, @prior if present
             uri = pending_uri or current_headers.get("uri")
+            by = current_headers.get("by")
             prior_str = current_headers.get("prior")
             prior = SourceRef(prior_str) if prior_str else None
 
             record = Record(
                 feedback=feedback or "",
                 uri=uri,
+                by=by,
                 source=source,
                 prior=prior,
                 content=None,

{markback-0.1.2 → markback-0.1.5}/markback/types.py

@@ -78,8 +78,9 @@ class Diagnostic:
         }
 
 
-# Regex to parse line range from a path: path:start or path:start-end
-_LINE_RANGE_PATTERN = re.compile(r'^(.+?):(\d+)(?:-(\d+))?$')
+# Regex to parse line/character range from a path
+# Supports: path:line, path:line:col, path:line-line, path:line:col-line:col
+_LINE_RANGE_PATTERN = re.compile(r'^(.+?):(\d+)(?::(\d+))?(?:-(\d+)(?::(\d+))?)?$')
 
 
 @dataclass
@@ -89,6 +90,8 @@ class SourceRef:
     is_uri: bool = False
     start_line: Optional[int] = None
     end_line: Optional[int] = None
+    start_column: Optional[int] = None
+    end_column: Optional[int] = None
     _path_only: str = ""
 
     def __post_init__(self):
@@ -102,16 +105,21 @@ class SourceRef:
             self.is_uri = bool(parsed.scheme) and len(parsed.scheme) > 1
 
     def _parse_line_range(self):
-        """Parse optional line range from value."""
+        """Parse optional line/character range from value."""
         match = _LINE_RANGE_PATTERN.match(self.value)
         if match:
             self._path_only = match.group(1)
             self.start_line = int(match.group(2))
             if match.group(3):
-                self.end_line = int(match.group(3))
+                self.start_column = int(match.group(3))
+            if match.group(4):
+                self.end_line = int(match.group(4))
+                if match.group(5):
+                    self.end_column = int(match.group(5))
             else:
-                # Single line reference: start and end are the same
+                # Single line/position reference: start and end are the same
                 self.end_line = self.start_line
+                self.end_column = self.start_column
         else:
             self._path_only = self.value
 
@@ -122,12 +130,27 @@ class SourceRef:
 
     @property
     def line_range_str(self) -> Optional[str]:
-        """Return formatted line range string, or None if no range."""
+        """Return formatted line/character range string, or None if no range."""
         if self.start_line is None:
             return None
-        if self.start_line == self.end_line:
-            return f":{self.start_line}"
-        return f":{self.start_line}-{self.end_line}"
+
+        # Build start position
+        if self.start_column is not None:
+            start = f":{self.start_line}:{self.start_column}"
+        else:
+            start = f":{self.start_line}"
+
+        # Check if end is the same as start (single position)
+        if self.start_line == self.end_line and self.start_column == self.end_column:
+            return start
+
+        # Build end position
+        if self.end_column is not None:
+            end = f"-{self.end_line}:{self.end_column}"
+        else:
+            end = f"-{self.end_line}"
+
+        return f"{start}{end}"
 
     def resolve(self, base_path: Optional[Path] = None) -> Path:
         """Resolve to a file path (relative paths resolved against base_path)."""
@@ -162,6 +185,7 @@ class Record:
     """A MarkBack record containing content and feedback."""
     feedback: str
     uri: Optional[str] = None
+    by: Optional[str] = None
     source: Optional[SourceRef] = None
     prior: Optional[SourceRef] = None
     content: Optional[str] = None
@@ -195,6 +219,7 @@ class Record:
         """Convert to JSON-serializable dict."""
         return {
             "uri": self.uri,
+            "by": self.by,
             "source": str(self.source) if self.source else None,
             "prior": str(self.prior) if self.prior else None,
             "content": self.content,

{markback-0.1.2 → markback-0.1.5}/markback/writer.py

@@ -38,17 +38,21 @@ def write_record_canonical(
     )
 
     if use_compact:
-        # Compact format: @uri on its own line (if present), then @prior, then @source ... <<<
+        # Compact format: @uri, @by, @prior on own lines (if present), then @source ... <<<
         if record.uri:
             lines.append(f"@uri {record.uri}")
+        if record.by:
+            lines.append(f"@by {record.by}")
         if record.prior:
             lines.append(f"@prior {record.prior}")
         lines.append(f"@source {record.source} <<< {record.feedback}")
     else:
         # Full format
-        # Headers: @uri first, then @prior, then @source
+        # Headers: @uri first, then @by, then @prior, then @source
         if record.uri:
             lines.append(f"@uri {record.uri}")
+        if record.by:
+            lines.append(f"@by {record.by}")
         if record.prior:
             lines.append(f"@prior {record.prior}")
         if record.source:
@@ -151,7 +155,10 @@ def write_label_file(record: Record) -> str:
 
     if record.uri:
         lines.append(f"@uri {record.uri}")
-    
+
+    if record.by:
+        lines.append(f"@by {record.by}")
+
     if record.prior:
         lines.append(f"@prior {record.prior}")
 

{markback-0.1.2 → markback-0.1.5}/packages/markbackjs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markbackjs",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "MarkBack tooling for JavaScript and TypeScript",
   "license": "MIT",
   "main": "dist/index.js",