markback 0.1.2__tar.gz → 0.1.3__tar.gz

{markback-0.1.2 → markback-0.1.3}/.claude/settings.local.json

@@ -7,7 +7,11 @@
       "Bash(npm run build:*)",
       "Bash(echo:*)",
       "Bash(python -m markback lint:*)",
-      "Bash(python:*)"
+      "Bash(python:*)",
+      "Bash(python3 -m pytest:*)",
+      "Bash(pip3 install:*)",
+      "Bash(.venv/bin/python -m pytest:*)",
+      "Bash(chmod:*)"
     ]
   }
 }

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markback
-Version: 0.1.2
+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.2 → 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,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.2 → markback-0.1.3}/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.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.2 → markback-0.1.3}/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.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.2 → 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.2 → markback-0.1.3}/packages/markbackjs/src/linter.ts

@@ -138,12 +138,36 @@ 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 line range
+  // Check @source range
   if (record.source && record.source.startLine !== null) {
-    if (record.source.endLine !== null && record.source.endLine < record.source.startLine) {
+    const { isInvalid, errorMsg } = isPositionInvalid(record.source);
+    if (isInvalid) {
       diagnostics.push(
         new Diagnostic({
           file: record._sourceFile ?? null,
@@ -151,16 +175,17 @@ function lintLineRange(record: MarkbackRecord, recordIdx: number): Diagnostic[]
           column: null,
           severity: Severity.ERROR,
           code: ErrorCode.E011,
-          message: `Invalid line range in @source: end line ${record.source.endLine} is less than start line ${record.source.startLine}`,
+          message: `Invalid range in @source: ${errorMsg}`,
           recordIndex: recordIdx,
         }),
       );
     }
   }
 
-  // Check @prior line range
+  // Check @prior range
   if (record.prior && record.prior.startLine !== null) {
-    if (record.prior.endLine !== null && record.prior.endLine < record.prior.startLine) {
+    const { isInvalid, errorMsg } = isPositionInvalid(record.prior);
+    if (isInvalid) {
       diagnostics.push(
         new Diagnostic({
           file: record._sourceFile ?? null,
@@ -168,7 +193,7 @@ function lintLineRange(record: MarkbackRecord, recordIdx: number): Diagnostic[]
           column: null,
           severity: Severity.ERROR,
           code: ErrorCode.E011,
-          message: `Invalid line range in @prior: end line ${record.prior.endLine} is less than start line ${record.prior.startLine}`,
+          message: `Invalid range in @prior: ${errorMsg}`,
           recordIndex: recordIdx,
         }),
       );

{markback-0.1.2 → 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,

{markback-0.1.2 → markback-0.1.3}/packages/markbackjs/src/types.ts

@@ -100,20 +100,25 @@ function extractScheme(value: string): string | null {
   return match ? match[1] : null;
 }
 
-// Regex to parse line range from a path: path:start or path:start-end
-const LINE_RANGE_PATTERN = /^(.+?):(\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
+const LINE_RANGE_PATTERN = /^(.+?):(\d+)(?::(\d+))?(?:-(\d+)(?::(\d+))?)?$/;
 
 export class SourceRef {
   value: string;
   isUri: boolean;
   startLine: number | null;
   endLine: number | null;
+  startColumn: number | null;
+  endColumn: number | null;
   private _pathOnly: string;
 
   constructor(value: string, isUri = false) {
     this.value = value;
     this.startLine = null;
     this.endLine = null;
+    this.startColumn = null;
+    this.endColumn = null;
     this._pathOnly = value;
 
     // Parse line range if present
@@ -135,10 +140,17 @@ export class SourceRef {
       this._pathOnly = match[1];
       this.startLine = parseInt(match[2], 10);
       if (match[3]) {
-        this.endLine = parseInt(match[3], 10);
+        this.startColumn = parseInt(match[3], 10);
+      }
+      if (match[4]) {
+        this.endLine = parseInt(match[4], 10);
+        if (match[5]) {
+          this.endColumn = parseInt(match[5], 10);
+        }
       } else {
-        // Single line reference: start and end are the same
+        // Single line/position reference: start and end are the same
         this.endLine = this.startLine;
+        this.endColumn = this.startColumn;
       }
     }
   }
@@ -151,10 +163,29 @@ export class SourceRef {
     if (this.startLine === null) {
       return null;
     }
-    if (this.startLine === this.endLine) {
-      return `:${this.startLine}`;
+
+    // Build start position
+    let start: string;
+    if (this.startColumn !== null) {
+      start = `:${this.startLine}:${this.startColumn}`;
+    } else {
+      start = `:${this.startLine}`;
+    }
+
+    // Check if end is the same as start (single position)
+    if (this.startLine === this.endLine && this.startColumn === this.endColumn) {
+      return start;
     }
-    return `:${this.startLine}-${this.endLine}`;
+
+    // Build end position
+    let end: string;
+    if (this.endColumn !== null) {
+      end = `-${this.endLine}:${this.endColumn}`;
+    } else {
+      end = `-${this.endLine}`;
+    }
+
+    return `${start}${end}`;
   }
 
   resolve(basePath?: string | null): string {
@@ -185,6 +216,7 @@ export class SourceRef {
 export interface RecordInit {
   feedback: string;
   uri?: string | null;
+  by?: string | null;
   source?: SourceRef | null;
   prior?: SourceRef | null;
   content?: string | null;
@@ -198,6 +230,7 @@ export interface RecordInit {
 export class Record {
   feedback: string;
   uri: string | null;
+  by: string | null;
   source: SourceRef | null;
   prior: SourceRef | null;
   content: string | null;
@@ -210,6 +243,7 @@ export class Record {
   constructor(init: RecordInit) {
     this.feedback = init.feedback;
     this.uri = init.uri ?? null;
+    this.by = init.by ?? null;
     this.source = init.source ?? null;
     this.prior = init.prior ?? null;
     this.content = init.content ?? null;
@@ -237,6 +271,7 @@ export class Record {
   toDict(): UnknownMap {
     return {
       uri: this.uri,
+      by: this.by,
       source: this.source ? this.source.toString() : null,
       prior: this.prior ? this.prior.toString() : null,
       content: this.content,

{markback-0.1.2 → markback-0.1.3}/packages/markbackjs/src/writer.ts

@@ -20,6 +20,9 @@ export function writeRecordCanonical(record: Record, preferCompact = true): stri
     if (record.uri) {
       lines.push(`@uri ${record.uri}`);
     }
+    if (record.by) {
+      lines.push(`@by ${record.by}`);
+    }
     if (record.prior) {
       lines.push(`@prior ${record.prior}`);
     }
@@ -28,6 +31,9 @@ export function writeRecordCanonical(record: Record, preferCompact = true): stri
     if (record.uri) {
       lines.push(`@uri ${record.uri}`);
     }
+    if (record.by) {
+      lines.push(`@by ${record.by}`);
+    }
     if (record.prior) {
       lines.push(`@prior ${record.prior}`);
     }

{markback-0.1.2 → markback-0.1.3}/packages/markbackjs/test/linter.test.js

@@ -159,3 +159,107 @@ test("lintString: source without line range still works", () => {
   assert.equal(result.records[0].source.startLine, null);
   assert.equal(result.records[0].source.endLine, null);
 });
+
+// @by header tests
+
+test("lintString: @by header basic", () => {
+  const text = "@uri local:example\n@by dan@example.com\n\nContent.\n<<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].by, "dan@example.com");
+});
+
+test("lintString: @by header with spaces", () => {
+  const text = "@uri local:example\n@by Dan Driscoll\n\nContent.\n<<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].by, "Dan Driscoll");
+});
+
+test("lintString: @by header with compact record", () => {
+  const text = "@uri local:item-001\n@by reviewer@example.com\n@source ./file.txt <<< feedback\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].by, "reviewer@example.com");
+});
+
+test("lintString: @by header with @prior", () => {
+  const text = "@uri local:gen-001\n@by ai-trainer@example.com\n@prior ./prompts/prompt.txt\n@source ./output.txt\n<<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].by, "ai-trainer@example.com");
+  assert.ok(result.records[0].prior !== null);
+});
+
+// Character-level referencing tests
+
+test("lintString: @source with single position (line:col)", () => {
+  const text = "@source ./code.py:42:10 <<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].source.path, "./code.py");
+  assert.equal(result.records[0].source.startLine, 42);
+  assert.equal(result.records[0].source.startColumn, 10);
+  assert.equal(result.records[0].source.endLine, 42);
+  assert.equal(result.records[0].source.endColumn, 10);
+});
+
+test("lintString: @source with character range same line", () => {
+  const text = "@source ./code.py:42:10-42:25 <<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].source.path, "./code.py");
+  assert.equal(result.records[0].source.startLine, 42);
+  assert.equal(result.records[0].source.startColumn, 10);
+  assert.equal(result.records[0].source.endLine, 42);
+  assert.equal(result.records[0].source.endColumn, 25);
+});
+
+test("lintString: @source with character range multi-line", () => {
+  const text = "@source ./code.py:10:5-15:20 <<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].source.path, "./code.py");
+  assert.equal(result.records[0].source.startLine, 10);
+  assert.equal(result.records[0].source.startColumn, 5);
+  assert.equal(result.records[0].source.endLine, 15);
+  assert.equal(result.records[0].source.endColumn, 20);
+});
+
+test("lintString: @prior with character range", () => {
+  const text = "@prior ./prompts/template.txt:1:1-20:50\n@source ./output.txt\n<<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].prior.path, "./prompts/template.txt");
+  assert.equal(result.records[0].prior.startLine, 1);
+  assert.equal(result.records[0].prior.startColumn, 1);
+  assert.equal(result.records[0].prior.endLine, 20);
+  assert.equal(result.records[0].prior.endColumn, 50);
+});
+
+test("lintString: invalid character range end col < start col", () => {
+  const text = "@source ./code.py:42:25-42:10 <<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, true);
+  assert.equal(findCode(result.diagnostics, ErrorCode.E011).length, 1);
+});
+
+test("lintString: line range without columns still works", () => {
+  const text = "@source ./code.py:10-20 <<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].source.startLine, 10);
+  assert.equal(result.records[0].source.startColumn, null);
+  assert.equal(result.records[0].source.endLine, 20);
+  assert.equal(result.records[0].source.endColumn, null);
+});
+
+test("lintString: mixed column specification", () => {
+  const text = "@source ./code.py:10:5-20 <<< good\n";
+  const result = lintString(text, { checkSources: false, checkCanonical: false });
+  assert.equal(result.hasErrors, false);
+  assert.equal(result.records[0].source.startLine, 10);
+  assert.equal(result.records[0].source.startColumn, 5);
+  assert.equal(result.records[0].source.endLine, 20);
+  assert.equal(result.records[0].source.endColumn, null);
+});

{markback-0.1.2 → markback-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "markback"
-version = "0.1.2"
+version = "0.1.3"
 description = "A compact, human-writable format for storing content paired with feedback/labels"
 readme = "README.md"
 license = "MIT"

markback-0.1.3/scripts/publish-npm.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+set -e
+
+# Publish JavaScript package to npm
+
+cd "$(dirname "$0")/../packages/markbackjs"
+
+echo "Building and publishing to npm..."
+npm publish
+
+echo "Done! Package published to npm."

markback-0.1.3/scripts/publish-pypi.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+set -e
+
+# Publish Python package to PyPI
+
+cd "$(dirname "$0")/.."
+
+echo "Building Python package..."
+python -m build
+
+echo "Uploading to PyPI..."
+python -m twine upload dist/*
+
+echo "Done! Package published to PyPI."

markback-0.1.3/scripts/publish.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+set -e
+
+# Publish both Python and JavaScript packages
+
+SCRIPT_DIR="$(dirname "$0")"
+
+echo "=== Publishing to PyPI ==="
+"$SCRIPT_DIR/publish-pypi.sh"
+
+echo ""
+echo "=== Publishing to npm ==="
+"$SCRIPT_DIR/publish-npm.sh"
+
+echo ""
+echo "All packages published successfully!"

{markback-0.1.2 → markback-0.1.3}/tests/test_linter.py

@@ -326,3 +326,130 @@ class TestLineRangeSupport:
         assert result.records[0].source.path == "./code.py"
         assert result.records[0].source.start_line is None
         assert result.records[0].source.end_line is None
+
+
+class TestByHeader:
+    """Tests for @by header support."""
+
+    def test_by_header_basic(self):
+        """Test basic @by header parsing."""
+        text = "@uri local:example\n@by dan@example.com\n\nContent.\n<<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].by == "dan@example.com"
+
+    def test_by_header_with_spaces(self):
+        """Test @by header with freeform text."""
+        text = "@uri local:example\n@by Dan Driscoll\n\nContent.\n<<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].by == "Dan Driscoll"
+
+    def test_by_header_compact_record(self):
+        """Test @by header with compact record."""
+        text = "@uri local:item-001\n@by reviewer@example.com\n@source ./file.txt <<< feedback\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].by == "reviewer@example.com"
+
+    def test_by_header_with_prior(self):
+        """Test @by header combined with @prior."""
+        text = "@uri local:gen-001\n@by ai-trainer@example.com\n@prior ./prompts/prompt.txt\n@source ./output.txt\n<<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].by == "ai-trainer@example.com"
+        assert result.records[0].prior is not None
+
+
+class TestCharacterLevelReferencing:
+    """Tests for character-level referencing syntax."""
+
+    def test_source_with_single_position(self):
+        """Test @source with single position (line:col)."""
+        text = "@source ./code.py:42:10 <<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].source is not None
+        assert result.records[0].source.path == "./code.py"
+        assert result.records[0].source.start_line == 42
+        assert result.records[0].source.start_column == 10
+        assert result.records[0].source.end_line == 42
+        assert result.records[0].source.end_column == 10
+
+    def test_source_with_character_range_same_line(self):
+        """Test @source with character range on same line."""
+        text = "@source ./code.py:42:10-42:25 <<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].source is not None
+        assert result.records[0].source.path == "./code.py"
+        assert result.records[0].source.start_line == 42
+        assert result.records[0].source.start_column == 10
+        assert result.records[0].source.end_line == 42
+        assert result.records[0].source.end_column == 25
+
+    def test_source_with_character_range_multi_line(self):
+        """Test @source with character range spanning multiple lines."""
+        text = "@source ./code.py:10:5-15:20 <<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].source is not None
+        assert result.records[0].source.path == "./code.py"
+        assert result.records[0].source.start_line == 10
+        assert result.records[0].source.start_column == 5
+        assert result.records[0].source.end_line == 15
+        assert result.records[0].source.end_column == 20
+
+    def test_prior_with_character_range(self):
+        """Test @prior with character range."""
+        text = "@prior ./prompts/template.txt:1:1-20:50\n@source ./output.txt\n<<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].prior is not None
+        assert result.records[0].prior.path == "./prompts/template.txt"
+        assert result.records[0].prior.start_line == 1
+        assert result.records[0].prior.start_column == 1
+        assert result.records[0].prior.end_line == 20
+        assert result.records[0].prior.end_column == 50
+
+    def test_invalid_character_range_end_column_less_than_start(self):
+        """Test E011: Invalid character range (end col < start col on same line)."""
+        text = "@source ./code.py:42:25-42:10 <<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert result.has_errors
+        errors = [d for d in result.diagnostics if d.code == ErrorCode.E011]
+        assert len(errors) == 1
+        assert "end column 10 is less than start column 25" in errors[0].message
+
+    def test_line_range_without_columns_still_works(self):
+        """Test that line ranges without columns still work."""
+        text = "@source ./code.py:10-20 <<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].source is not None
+        assert result.records[0].source.start_line == 10
+        assert result.records[0].source.start_column is None
+        assert result.records[0].source.end_line == 20
+        assert result.records[0].source.end_column is None
+
+    def test_mixed_column_specification(self):
+        """Test range with start column but no end column."""
+        text = "@source ./code.py:10:5-20 <<< good\n"
+        result = lint_string(text, check_sources=False, check_canonical=False)
+
+        assert not result.has_errors
+        assert result.records[0].source is not None
+        assert result.records[0].source.start_line == 10
+        assert result.records[0].source.start_column == 5
+        assert result.records[0].source.end_line == 20
+        assert result.records[0].source.end_column is None