@entropicwarrior/sdoc 0.1.17 → 0.2.0

package/docs/reference/sdoc-authoring.sdoc

@@ -4,7 +4,7 @@
     {
         type: skill
 
-        sdoc-version: 0.1
+        sdoc-version: 0.2
     }
 
     # About @about
@@ -178,7 +178,7 @@ Content of Section B.
 
             **Important:** \`{[.]}\` with the closing brace on the same line creates an empty list — the brace closes the block immediately. Always put the closing \`}\` on a separate line after the items.
 
-            Implicit lists only work for bullet lists (\`-\`) where every item is a single line. For numbered lists, always use the explicit \`{[#]\` block form.
+            Implicit lists work for both bullet (\`-\`) and numbered (\`1.\`, \`2.\`, etc.) items. Each item must be a single line. For multi-line item titles or item body content, use the explicit \`{[.]}\` or \`{[#]\` block form.
 
             **Task lists** — checkbox syntax inside explicit list blocks:
 
@@ -244,6 +244,27 @@ Content of Section B.
             ```
 
             \`borderless\` removes borders and row striping. \`headerless\` treats all rows as data (no header). Flags combine in any order.
+
+            Width and alignment flags control table sizing and position:
+
+            ```
+            {[table 60% center]
+                Endpoint | Status
+                /v2/weather | Active
+            }
+
+            {[table auto]
+                Key | Value
+                Version | 2.0
+            }
+
+            {[table 400px right borderless]
+                v2.0 | Current
+                v1.0 | Deprecated
+            }
+            ```
+
+            Width: \`auto\` (shrink to content), \`NN%\` (percentage), or \`NNpx\` (pixels). Default is 100%. Alignment: \`left\` (default), \`center\`, or \`right\`. All flags compose freely in any order.
         }
 
         # Inline Formatting @inline-formatting
@@ -279,7 +300,7 @@ Content of Section B.
             ![A](a.png =48%) ![B](b.png =48%)
             ```
 
-            Autolinks: \`\<https://example.com\>\`
+            Autolinks: \`\<https://example.com\>\` — angle brackets are optional; bare URLs starting with \`http://\`, \`https://\`, or \`mailto:\` are also auto-linked.
 
             Math: Use \`\$...\$\` for inline math and \`\$\$...\$\$\` for display math. Use \`\\\`\\\`\\\`math\` code fences for multi-line equations. A plain \`\$\` followed by a digit (e.g. \`\$100\`) does not trigger math mode.
         }
@@ -380,7 +401,7 @@ Content of Section B.
             @meta {
                 type: doc
 
-                sdoc-version: 0.1
+                sdoc-version: 0.2
 
                 company: Irreversible Inc.
 
@@ -420,7 +441,7 @@ Content of Section B.
 
             \`tags: tag1, tag2\` — comma-separated tags.
 
-            \`sdoc-version: 0.1\` — SDOC format version. A parser warning is
+            \`sdoc-version: 0.2\` — SDOC format version. A parser warning is
             emitted when this key is missing from \`@meta\`.
         }
 
@@ -441,7 +462,7 @@ Content of Section B.
         {
             Backslash escapes special characters: \`\\\\\` \`\\{\` \`\\}\` \`\\@\`
             \`\\[\` \`\\]\` \`\\(\` \`\\)\` \`\\*\` \`\\~\` \`\\#\` \`\\!\` \`\\\<\`
-            \`\\\>\` \`\\\$\` \`\\+\` \`\\=\` \`\\-\` \`\\^\`
+            \`\\\>\` \`\\\$\` \`\\+\` \`\\=\` \`\\-\` \`\\^\` \`\\?\`
 
             A line starting with \`\\#\` renders as a literal \`#\` (not a heading). Use \`\\\$\` to prevent a dollar sign from starting math mode.
         }
@@ -454,6 +475,89 @@ Content of Section B.
                 - **Commas:** commas between list items or scopes are allowed but ignored — use them if you find them readable.
             }
         }
+
+        # Scope Types @scope-types
+        {
+            A \`:type\` annotation on a heading gives the scope semantic meaning. Place it after the optional \`@id\`:
+
+            ```
+            # User Authentication @auth :requirement
+            {
+                The system shall authenticate users via OAuth 2.0.
+            }
+
+            # OAuth Flow :specification @oauth-flow
+            {
+                Implements @auth using the authorization code flow.
+            }
+
+            # Deprecation Notice :warning
+            {
+                This API will be removed in v3.0.
+            }
+            ```
+
+            {[.]
+                - Syntax: \`# Title @id :type\` or \`# Title :type @id\` or \`# Title :type\` — both orderings work
+                - The colon requires whitespace before it: \`# Note: Important\` is NOT a type — the colon is part of the title
+                - Any string is valid. Well-known types: \`schema\`, \`example\`, \`requirement\`, \`specification\`, \`definition\`, \`note\`, \`warning\`, \`test\`, \`task\`, \`api\`, \`config\`, \`deprecated\`, \`comment\`
+                - Works with K&R style: \`# Title :warning {\`
+            }
+
+            The special type \`:comment\` makes a scope that is in the AST but not rendered — useful for editorial notes and AI agent instructions:
+
+            ```
+            # TODO :comment
+            {
+                Rewrite this section after the API stabilises.
+            }
+            ```
+        }
+
+        # Data Blocks @data-blocks
+        {
+            Add \`:data\` to a JSON code fence to have the parser parse the content into structured data on the AST node:
+
+            `````
+            ```json :data
+            {
+                "name": "SDOC",
+                "version": "0.2",
+                "features": ["scopes", "lists", "tables"]
+            }
+            ```
+            `````
+
+            {[.]
+                - Syntax: \` \`\`\`json :data \` — the \`:data\` flag follows the language tag
+                - Invalid JSON produces a parse error
+                - JSON-only in v0.2
+                - Without \`:data\`, JSON code blocks remain raw text (existing behaviour)
+            }
+        }
+
+        # Comments @comments
+        {
+            **Line comments** — \`//\` at the start of a line (after optional indentation) skips the line entirely. Not in the AST, not rendered:
+
+            ```
+            # Config @config
+            {
+                // TODO: add validation
+                The config file uses JSON format.
+
+                // hidden from output
+                See @setup for details.
+            }
+            ```
+
+            {[.]
+                - Mid-line \`//\` has no effect — URLs like \`https://example.com\` are safe
+                - Inside code blocks: \`//\` has no special meaning
+            }
+
+            **Comment scopes** — use the \`:comment\` scope type for structured non-rendered content (see @scope-types above).
+        }
     }
 
     # Common Mistakes @common-mistakes

package/lexica/specification.sdoc

@@ -1,19 +1,20 @@
-# SDOC Specification v0.1 @sdoc-spec
+# SDOC Specification v0.2 @sdoc-spec
 {
     # Meta @meta
     {
         type: doc
 
-        sdoc-version: 0.1
+        sdoc-version: 0.2
     }
 
     # About @about
     {
-        The formal SDOC v0.1 specification. Defines syntax for scopes,
-        lists, tables, code blocks, inline formatting, references, and
-        the meta scope. Includes the formal EBNF grammar. Read for
-        edge cases and parser behaviour questions. For a friendlier
-        user-facing reference, see \`docs/reference/syntax.sdoc\`.
+        The formal SDOC v0.2 specification. Defines syntax for scopes,
+        lists, tables, code blocks, inline formatting, references,
+        the meta scope, scope types, data blocks, and comments.
+        Includes the formal EBNF grammar. Read for edge cases and
+        parser behaviour questions. For a friendlier user-facing
+        reference, see \`docs/reference/syntax.sdoc\`.
     }
 
     # Overview @overview
@@ -51,12 +52,17 @@
         {
             ```
             # Title text @id
+            # Title text @id :type
+            # Title text :type @id
+            # Title text :type
             ```
 
             {[.]
                 - The line must start with `#` (after optional indentation)
                 - Multiple `#` characters are allowed but do not affect depth. Depth comes only from scope nesting
-                - The optional `@id` must appear at the end of the line, separated by whitespace
+                - The optional `@id` must appear at the end of the line (or before `:type`), separated by whitespace
+                - The optional `:type` assigns a scope type (see @scope-types). Both `@id :type` and `:type @id` orderings are valid
+                - `:type` requires whitespace before the colon, so `# Note: Important` is NOT a scope type — the colon is part of the title
                 - If no `@id` is present, the scope has no ID
                 - If you need a literal `@` in the title, escape it (`\@`)
             }
@@ -122,7 +128,7 @@ Content of Section B.
                     - The opener must be the last token on the line (trailing whitespace is allowed)
                     - Applies to `{`, `{[.]`, `{[#]`, `{[table]`, and `{[table <flags>]`
                     - Also works on list-item shorthand lines (e.g., `- Item {`)
-                    - Table options (e.g., `{[table borderless]`) work in K&R style: `# Data {[table borderless]`
+                    - Table options (e.g., `{[table borderless]`, `{[table 60% center]`) work in K&R style: `# Data {[table borderless]`
                     - Escaped braces (`\{`) are not treated as openers
                     - The closing `}` must still appear on its own line
                     - Inline blocks (`{ content }`) are not affected; a line ending with `}` is not treated as K&R
@@ -344,9 +350,33 @@ Content of Section B.
                 {[.]
                     - `borderless` removes all table borders and row striping
                     - `headerless` treats the first row as data (no header row)
-                    - Flags can be combined in any order
+                    - `auto` sets width to shrink-to-content
+                    - A percentage value (e.g. `60%`, `33.3%`) sets an explicit percentage width
+                    - A pixel value (e.g. `400px`) sets an explicit pixel width
+                    - `center` centers the table (auto margins)
+                    - `right` right-aligns the table (margin-left: auto)
+                    - `left` left-aligns the table (default, no extra styles)
+                    - Default width is 100%; default alignment is left
+                    - All flags can be combined in any order
                     - Works with both Allman and K&R brace styles
                 }
+
+                ```
+{[table 60% center]
+    Endpoint | Status
+    /v2/weather | Active
+}
+
+{[table auto right borderless]
+    Key | Value
+    Version | 2.0
+}
+
+{[table 400px]
+    Name | Age
+    Alice | 30
+}
+                ```
             }
         }
 
@@ -387,6 +417,8 @@ Content of Section B.
             ```
 
             Only `http`, `https`, and `mailto` schemes are recognised.
+
+            Bare URLs starting with `http://`, `https://`, or `mailto:` are also auto-linked without angle brackets.
         }
 
         # Images @images
@@ -466,7 +498,7 @@ Content of Section B.
 
         # Escaping @escaping
         {
-            In normal text (including headings and paragraphs), a backslash escapes: `\\` `\{` `\}` `\@` `\[` `\]` `\(` `\)` `\*` `\~` `\#` `\!` `\<` `\>` `\$` `\+` `\=` `\-` `\^` and `` \` ``.
+            In normal text (including headings and paragraphs), a backslash escapes: `\\` `\{` `\}` `\@` `\[` `\]` `\(` `\)` `\*` `\~` `\#` `\!` `\<` `\>` `\$` `\+` `\=` `\-` `\^` `\?` and `` \` ``.
 
             Escapes are processed before reference detection.
 
@@ -516,6 +548,115 @@ Content of Section B.
                 }
             }
         }
+
+        # Scope Types @scope-types
+        {
+            A scope type annotation provides semantic meaning to a scope. The type is specified with `:typename` on the heading line, after optional `@id`:
+
+            ```
+            # User Authentication @auth :requirement
+            {
+                The system shall authenticate users via OAuth 2.0.
+            }
+
+            # OAuth Flow :specification @oauth-flow
+            {
+                Implements @auth using the authorization code flow.
+            }
+
+            # Important :warning
+            {
+                This API is deprecated and will be removed in v3.0.
+            }
+            ```
+
+            {[.]
+                - Syntax: `# Title @id :type` or `# Title :type @id` or `# Title :type` — both orderings of `@id` and `:type` are supported
+                - The colon in `:type` requires whitespace before it, so `# Note: Important` is NOT a scope type — the colon is part of the title text
+                - Any string is valid as a type name
+                - Well-known types: `schema`, `example`, `requirement`, `specification`, `definition`, `note`, `warning`, `test`, `task`, `api`, `config`, `deprecated`, `comment`
+                - The type is stored on the AST node and available to renderers and tooling
+                - Scope types enable AI agents to filter and navigate by semantic meaning (e.g., "show all requirements", "find tests for this spec")
+                - Works with K&R brace style: `# Title :warning {`
+            }
+
+            # Comment Scopes @comment-scopes
+            {
+                The `:comment` scope type creates a scope that is present in the AST but not rendered in the document output. This is useful for editorial annotations, AI agent instructions, and internal notes:
+
+                ```
+                # TODO :comment
+                {
+                    Rewrite this section after the API stabilises.
+                    @alice please review the error handling.
+                }
+
+                # Agent Instructions :comment
+                {
+                    When summarising this document, focus on the
+                    requirements and skip the implementation details.
+                }
+                ```
+
+                {[.]
+                    - Comment scopes use the standard scope type system — no special syntax beyond `:comment`
+                    - The scope is parsed into the AST (agents and tooling can extract it)
+                    - The scope is not rendered in HTML, PDF, or other visual outputs
+                    - Comment scopes can contain any valid SDOC content (paragraphs, lists, code blocks, nested scopes)
+                    - Useful for structured annotations that are too complex for line comments
+                }
+            }
+        }
+
+        # Data Blocks @data-blocks
+        {
+            A code fence with the `:data` flag causes the parser to parse the content as structured data and attach it to the AST node:
+
+            `````
+            ```json :data
+            {
+                "name": "SDOC",
+                "version": "0.2",
+                "features": ["scopes", "lists", "tables"]
+            }
+            ```
+            `````
+
+            {[.]
+                - Syntax: ` ```json :data ` — the `:data` flag follows the language tag on the opening fence line
+                - The parser parses the JSON content and stores the result on the AST node
+                - Invalid JSON produces a parse error
+                - JSON is the only supported data format in v0.2
+                - Without the `:data` flag, JSON code blocks are treated as raw text (existing behaviour)
+                - Data blocks render visually the same as regular code blocks, but the parsed data is available to tooling and agents
+            }
+        }
+
+        # Line Comments @line-comments
+        {
+            A line starting with `//` (after optional indentation) is a line comment. The line is skipped entirely — it does not appear in the AST and is not rendered:
+
+            ```
+            # Configuration @config
+            {
+                // TODO: add validation rules
+                The config file uses JSON format.
+
+                // This paragraph is hidden from output
+                // but visible in the source file.
+
+                See @setup for installation steps.
+            }
+            ```
+
+            {[.]
+                - The `//` must be at the start of the line (after optional whitespace)
+                - Comment lines are discarded during parsing — they are not present in the AST
+                - Inside code blocks: `//` has no special meaning (code block content is raw)
+                - Mid-line `//` has no special meaning — URLs like `https://example.com` are safe
+                - Use line comments for quick annotations; use comment scopes (@comment-scopes) for structured non-rendered content
+            }
+        }
     }
 
     # Styles, Header, and Footer @styling
@@ -585,7 +726,7 @@ Content of Section B.
                     date: 2026-02-09
                     version: 1.0
                     status: Draft
-                    sdoc-version: 0.1
+                    sdoc-version: 0.2
                 }
                 ```
 
@@ -593,7 +734,7 @@ Content of Section B.
                     - Key matching is case-insensitive
                     - The pattern requires at least one space after the colon (`key: value`, not `key:value`)
                     - Well-known keys: `style`, `styleappend`/`style-append`, `header`, `footer`, `sdoc-version`
-                    - `sdoc-version` identifies the SDOC format version the document targets (current: `0.1`). A parser warning is emitted when this key is missing.
+                    - `sdoc-version` identifies the SDOC format version the document targets (current: `0.2`). A parser warning is emitted when this key is missing.
                     - All other keys are stored as custom properties (e.g., `author`, `date`, `version`, `status`, `tags`)
                     - Sub-scope syntax takes precedence: if both `# Style { path }` and `style: path` exist, the sub-scope value wins
                     - Key:value and sub-scope syntax can be mixed freely in the same meta scope
@@ -713,6 +854,7 @@ Content of Section A.
             - `>` blockquote line
             - `---` / `***` / `___` horizontal rule
             - `` ``` `` code fence
+            - `//` line comment (discarded, not in AST)
         }
 
         Blank lines are allowed anywhere and are ignored.
@@ -731,25 +873,34 @@ Content of Section A.
         scope         = heading ws? block
                       | heading ws? braceless_body
                       | heading_with_opener block_body "}" ;
-        heading       = "#" { "#" } ws title (ws id)? ;
-        heading_with_opener = "#" { "#" } ws title (ws id)? ws block_opener ;
+        heading       = "#" { "#" } ws title
+                          ((ws id)? (ws scope_type)? | (ws scope_type)? (ws id)?) ;
+        heading_with_opener = "#" { "#" } ws title
+                          ((ws id)? (ws scope_type)? | (ws scope_type)? (ws id)?) ws block_opener ;
         id            = "@" ident ;
+        scope_type    = ":" ident ;   (* id and scope_type may appear in either order *)
         block_opener  = "{" | "{[.]" | "{[#]" | table_open ;
         block         = "{" ws? block_body "}" ;
-        braceless_body = { paragraph | code_block | blockquote | implicit_list
-                         | horizontal_rule | headingless_scope | table_scope
-                         | blank } ;
-
-        block_body    = { blank | paragraph | scope | headingless_scope
-                        | list_scope | table_scope
+        braceless_body = { paragraph | code_block | data_block | blockquote
+                         | implicit_list | horizontal_rule | headingless_scope
+                         | list_scope | table_scope | bare_directive
+                         | line_comment | blank } ;
+
+        bare_directive = "@" ("meta" | "about") (ws block | braceless_body) ;
+        block_body    = { blank | line_comment | paragraph | scope
+                        | headingless_scope | list_scope | table_scope
                         | implicit_list | blockquote | horizontal_rule
-                        | code_block | comma_sep } ;
+                        | code_block | data_block | bare_directive | comma_sep } ;
         headingless_scope = "{" ws? block_body "}" ;
         list_scope    = list_open ws? list_body "}" ;
         list_open     = "{[.]" | "{[#]" ;
         table_scope   = table_open ws? table_body "}" ;
         table_open    = "{[table" { ws table_flag } "]" ;
-        table_flag    = "borderless" | "headerless" ;
+        table_flag    = "borderless" | "headerless"
+                      | "auto" | percentage | pixels
+                      | "left" | "center" | "right" ;
+        percentage    = digit { digit } [ "." digit { digit } ] "%" ;
+        pixels        = digit { digit } "px" ;
         table_body    = table_row { table_row } ;
         table_row     = cell { "|" cell } ;
         list_body     = { blank | comma_sep | scope | list_item_shorthand
@@ -767,15 +918,19 @@ Content of Section A.
         paragraph     = text_line { ws? text_line } ;
         text_line     = line_not_starting_with_command ;
 
-        blockquote    = quote_line { quote_line | blank } ;
+        blockquote    = quote_line { quote_line } ;
         quote_line    = ">" text_line ;
 
         horizontal_rule = "---" | "***" | "___" ;
 
         code_block    = fence_open raw_text fence_close ;
+        data_block    = data_fence_open raw_text fence_close ;
         fence_open    = "```" [lang] [ws "src:" path] [ws "lines:" range] newline ;
+        data_fence_open = "```" lang ws ":data" newline ;
         fence_close   = "```" newline ;
 
+        line_comment  = "//" { any_char } newline ;  (* discarded, not in AST *)
+
         comma_sep     = "," ;
         blank         = newline ;
 
@@ -783,7 +938,10 @@ Content of Section A.
         ```
 
         {[.]
-            - `title` is the remainder of the heading line, excluding the optional trailing `@id`
+            - `title` is the remainder of the heading line, excluding the optional trailing `@id` and `:type`
+            - `scope_type` and `id` may appear in either order after the title
+            - `line_comment` lines are discarded during parsing and do not appear in the AST
+            - `data_block` content is parsed as JSON; invalid JSON produces a parse error
             - If a line starts with a command token, it is not a paragraph line
             - The grammar is line-oriented; practical parsers should operate on lines
         }
@@ -792,10 +950,10 @@ Content of Section A.
     # Open Questions @open-questions
     {
         {[.]
-            - Comment syntax (if any)
             - Duplicate ID resolution (error vs warning vs nearest-scope)
-            - Additional list types (checkboxes, alpha, roman)
+            - Additional list types (alpha, roman)
             - Additional inline formatting (underline)
+            - Additional data block formats beyond JSON (YAML, TOML)
         }
     }
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@entropicwarrior/sdoc",
   "displayName": "SDOC",
   "description": "A plain-text documentation format with explicit brace scoping — deterministic parsing, AI-agent efficiency, and 10-50x token savings vs Markdown.",
-  "version": "0.1.17",
+  "version": "0.2.0",
   "publisher": "entropicwarrior",
   "license": "MIT",
   "repository": {

package/src/notion-renderer.js

@@ -246,6 +246,7 @@ function renderNotionBlocks(nodes) {
   // Unwrap document scope wrapper (single root scope)
   if (nodes.length === 1 && nodes[0].type === "scope" && nodes[0].children) {
     const doc = nodes[0];
+    if (doc.scopeType === "comment") return [];
     if (doc.hasHeading && doc.title) {
       // Document title scope: render as top-level toggle heading
       const childBlocks = renderChildren(doc.children, 2, 1);
@@ -290,6 +291,8 @@ function renderNode(node, depth, nestLevel) {
 }
 
 function renderScope(scope, depth, nestLevel) {
+  if (scope.scopeType === "comment") return [];
+
   const level = Math.min(3, Math.max(1, depth));
 
   if (scope.hasHeading === false) {