markback 0.1.1__tar.gz → 0.1.3__tar.gz

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

@@ -0,0 +1,17 @@
+{
+  "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:*)"
+    ]
+  }
+}

{markback-0.1.1 → markback-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markback
-Version: 0.1.1
+Version: 0.1.3
 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

{markback-0.1.1 → markback-0.1.3}/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,6 +145,37 @@ 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.5 Line and Character Range Specification
+
+Both `@source` and `@prior` headers support optional line and character range specifications using colon notation. This allows referencing specific positions within a file.
+
+**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 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)
+- 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
 
 Content is everything between headers and the `<<<` feedback delimiter.
@@ -460,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
@@ -575,6 +624,7 @@ Each line is classified as one of:
 | E008 | Unclosed quote in structured attribute value (only in `structured` parse mode) |
 | E009 | Empty feedback (nothing after `<<< `) |
 | E010 | Missing blank line before inline content (content starts with `@`) |
+| E011 | Invalid line range (end line less than start line) |
 
 ### 7.2 Warnings (SHOULD fix)
 
@@ -656,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`
 ```
@@ -666,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`
 ```
@@ -698,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`
 ```
@@ -729,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`
 ```
@@ -745,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:
 
@@ -768,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
@@ -777,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)
 
@@ -860,11 +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
-source-feedback-line = "@source" SP path SP "<<<" SP feedback-content LF
-path            = 1*VCHAR             ; ends at space before <<<
+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 [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.1 → markback-0.1.3}/markback/linter.py

@@ -137,6 +137,67 @@ 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/character ranges are valid (end position >= start position)."""
+    diagnostics: list[Diagnostic] = []
+
+    # Check @source range
+    if record.source and record.source.start_line is not None:
+        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 range in @source: {error_msg}",
+                record_index=record_idx,
+            ))
+
+    # Check @prior range
+    if record.prior and record.prior.start_line is not None:
+        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 range in @prior: {error_msg}",
+                record_index=record_idx,
+            ))
+
+    return diagnostics
+
+
 def lint_canonical_format(
     records: list[Record],
     original_text: str,
@@ -206,6 +267,9 @@ def lint_string(
             result.diagnostics.extend(lint_source_exists(record, base_path, idx))
             result.diagnostics.extend(lint_prior_exists(record, base_path, idx))
 
+        # Check line range validity
+        result.diagnostics.extend(lint_line_range(record, idx))
+
     # Check canonical format
     if check_canonical and result.records and not result.has_errors:
         result.diagnostics.extend(lint_canonical_format(

{markback-0.1.1 → markback-0.1.3}/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.1 → markback-0.1.3}/markback/types.py

@@ -1,5 +1,6 @@
 """Core types for MarkBack format."""
 
+import re
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
@@ -25,6 +26,7 @@ class ErrorCode(Enum):
     E008 = "E008"  # Unclosed quote in structured attribute value
     E009 = "E009"  # Empty feedback (nothing after <<< )
     E010 = "E010"  # Missing blank line before inline content
+    E011 = "E011"  # Invalid line range (end < start)
 
 
 class WarningCode(Enum):
@@ -76,29 +78,90 @@ class Diagnostic:
         }
 
 
+# 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
 class SourceRef:
     """Reference to external content (file path or URI)."""
     value: str
     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):
-        # Determine if this is a URI or file path
+        # Parse line range if present
+        self._parse_line_range()
+
+        # Determine if this is a URI or file path (using path without line range)
         if not self.is_uri:
-            parsed = urlparse(self.value)
+            parsed = urlparse(self._path_only)
             # Consider it a URI if it has a scheme that's not a Windows drive letter
             self.is_uri = bool(parsed.scheme) and len(parsed.scheme) > 1
 
+    def _parse_line_range(self):
+        """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.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/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
+
+    @property
+    def path(self) -> str:
+        """Return path without line range."""
+        return self._path_only
+
+    @property
+    def line_range_str(self) -> Optional[str]:
+        """Return formatted line/character range string, or None if no range."""
+        if self.start_line is None:
+            return None
+
+        # 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)."""
         if self.is_uri:
-            parsed = urlparse(self.value)
+            parsed = urlparse(self._path_only)
             if parsed.scheme == "file":
                 # file:// URI
                 return Path(parsed.path)
             raise ValueError(f"Cannot resolve non-file URI to path: {self.value}")
 
-        path = Path(self.value)
+        path = Path(self._path_only)
         if path.is_absolute():
             return path
         if base_path:
@@ -122,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
@@ -155,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.1 → markback-0.1.3}/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.1 → markback-0.1.3}/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",

{markback-0.1.1 → markback-0.1.3}/packages/markbackjs/src/linter.ts

@@ -138,6 +138,71 @@ function lintPriorExists(record: MarkbackRecord, basePath: string | null, record
   return diagnostics;
 }
 
+interface PositionCheck {
+  isInvalid: boolean;
+  errorMsg: string;
+}
+
+function isPositionInvalid(sourceRef: { startLine: number | null; endLine: number | null; startColumn: number | null; endColumn: number | null }): PositionCheck {
+  if (sourceRef.startLine === null || sourceRef.endLine === null) {
+    return { isInvalid: false, errorMsg: "" };
+  }
+
+  if (sourceRef.endLine < sourceRef.startLine) {
+    return { isInvalid: true, errorMsg: `end line ${sourceRef.endLine} is less than start line ${sourceRef.startLine}` };
+  }
+
+  if (sourceRef.endLine === sourceRef.startLine) {
+    if (sourceRef.startColumn !== null && sourceRef.endColumn !== null && sourceRef.endColumn < sourceRef.startColumn) {
+      return { isInvalid: true, errorMsg: `end column ${sourceRef.endColumn} is less than start column ${sourceRef.startColumn} on line ${sourceRef.startLine}` };
+    }
+  }
+
+  return { isInvalid: false, errorMsg: "" };
+}
+
+function lintLineRange(record: MarkbackRecord, recordIdx: number): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+
+  // Check @source range
+  if (record.source && record.source.startLine !== null) {
+    const { isInvalid, errorMsg } = isPositionInvalid(record.source);
+    if (isInvalid) {
+      diagnostics.push(
+        new Diagnostic({
+          file: record._sourceFile ?? null,
+          line: record._startLine ?? null,
+          column: null,
+          severity: Severity.ERROR,
+          code: ErrorCode.E011,
+          message: `Invalid range in @source: ${errorMsg}`,
+          recordIndex: recordIdx,
+        }),
+      );
+    }
+  }
+
+  // Check @prior range
+  if (record.prior && record.prior.startLine !== null) {
+    const { isInvalid, errorMsg } = isPositionInvalid(record.prior);
+    if (isInvalid) {
+      diagnostics.push(
+        new Diagnostic({
+          file: record._sourceFile ?? null,
+          line: record._startLine ?? null,
+          column: null,
+          severity: Severity.ERROR,
+          code: ErrorCode.E011,
+          message: `Invalid range in @prior: ${errorMsg}`,
+          recordIndex: recordIdx,
+        }),
+      );
+    }
+  }
+
+  return diagnostics;
+}
+
 function lintCanonicalFormat(records: MarkbackRecord[], originalText: string, file?: string | null): Diagnostic[] {
   const diagnostics: Diagnostic[] = [];
 
@@ -199,6 +264,9 @@ export function lintString(text: string, options: LintOptions = {}): ParseResult
       result.diagnostics.push(...lintSourceExists(record, basePath, idx));
       result.diagnostics.push(...lintPriorExists(record, basePath, idx));
     }
+
+    // Check line range validity
+    result.diagnostics.push(...lintLineRange(record, idx));
   });
 
   if (checkCanonical && result.records.length > 0 && !result.hasErrors) {

{markback-0.1.1 → markback-0.1.3}/packages/markbackjs/src/parser.ts

@@ -1,6 +1,6 @@
 import { Diagnostic, ErrorCode, ParseResult, Record as MarkbackRecord, Severity, SourceRef, WarningCode } from "./types";
 
-const KNOWN_HEADERS = new Set(["uri", "source", "prior"]);
+const KNOWN_HEADERS = new Set(["uri", "by", "source", "prior"]);
 
 const HEADER_PATTERN = /^@([a-z]+)\s+(.+)$/;
 const FEEDBACK_DELIMITER = "<<<";
@@ -114,6 +114,7 @@ export function parseString(text: string, sourceFile?: string | null): ParseResu
 
   const finalizeRecord = (feedback: string, endLine: number, isCompact = false) => {
     const uri = currentHeaders.uri ?? pendingUri;
+    const by = currentHeaders.by ?? null;
     const sourceStr = currentHeaders.source;
     const source = sourceStr ? new SourceRef(sourceStr) : null;
     const priorStr = currentHeaders.prior;
@@ -135,6 +136,7 @@ export function parseString(text: string, sourceFile?: string | null): ParseResu
       new MarkbackRecord({
         feedback,
         uri: uri ?? null,
+        by,
         source,
         prior,
         content,
@@ -202,13 +204,15 @@ export function parseString(text: string, sourceFile?: string | null): ParseResu
       }
 
       const uri = pendingUri ?? currentHeaders.uri ?? null;
+      const by = currentHeaders.by ?? null;
       const priorStr = currentHeaders.prior;
       const prior = priorStr ? new SourceRef(priorStr) : null;
 
       records.push(
-      new MarkbackRecord({
+        new MarkbackRecord({
           feedback: feedback ?? "",
           uri,
+          by,
           source,
           prior,
           content: null,