@shoalrun/cli 0.1.0-beta.1 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoalrun/cli",
-  "version": "0.1.0-beta.1",
+  "version": "1.0.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
@@ -11,6 +11,7 @@
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
+    "./references": "./dist/code-reference-model.js",
     "./content": "./dist/content-delivery.js",
     "./authoring": "./dist/authoring-api.js",
     "./*": "./*",
@@ -27,6 +28,7 @@
     "templates",
     "examples",
     "!examples/**/public/**",
+    "!examples/**/site-dist/**",
     "!examples/**/node_modules/**",
     "example-configs",
     "!example-configs/**/.shoalrun/**",
@@ -34,7 +36,12 @@
     "skills",
     "README.md",
     "AUTHORING.md",
+    "CODE-REFERENCES.md",
     "DEPLOYMENT-PROFILES.md",
+    "schemas/code-reference.schema.json",
+    "adapters/python",
+    "!**/__pycache__/**",
+    "!adapters/python/test_*.py",
     "schemas/content-export.schema.json",
     "schemas/content-rest.openapi.json",
     "CHANGELOG.md",

package/schemas/code-reference.schema.json

@@ -0,0 +1,306 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "kind": {
+      "type": "string",
+      "const": "shoalrun-code-reference"
+    },
+    "programmingLanguage": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+    },
+    "producer": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "extractorVersion": {
+          "type": "string",
+          "maxLength": 100
+        }
+      },
+      "required": [
+        "name",
+        "version"
+      ],
+      "additionalProperties": false
+    },
+    "sourceDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "symbols": {
+      "minItems": 1,
+      "maxItems": 10000,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512,
+            "pattern": "^[^\\s\\x00-\\x1f]+$"
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "module",
+              "namespace",
+              "class",
+              "interface",
+              "enum",
+              "type",
+              "function",
+              "method",
+              "constructor",
+              "property",
+              "attribute",
+              "constant"
+            ]
+          },
+          "parent": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512,
+            "pattern": "^[^\\s\\x00-\\x1f]+$"
+          },
+          "visibility": {
+            "default": "public",
+            "type": "string",
+            "enum": [
+              "public",
+              "private"
+            ]
+          },
+          "summary": {
+            "type": "string",
+            "maxLength": 1000
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 100000
+          },
+          "annotation": {
+            "type": "string",
+            "maxLength": 100000
+          },
+          "default": {
+            "type": "string",
+            "maxLength": 100000
+          },
+          "required": {
+            "type": "boolean"
+          },
+          "bases": {
+            "maxItems": 100,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "maxLength": 100000
+            }
+          },
+          "constructorSignature": {
+            "type": "string",
+            "maxLength": 100000
+          },
+          "typeReferences": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512
+            },
+            "additionalProperties": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[^\\s\\x00-\\x1f]+$"
+            }
+          },
+          "signatures": {
+            "maxItems": 100,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "maxLength": 100000
+            }
+          },
+          "parameters": {
+            "maxItems": 1000,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 512
+                },
+                "type": {
+                  "type": "string",
+                  "maxLength": 100000
+                },
+                "description": {
+                  "type": "string",
+                  "maxLength": 100000
+                },
+                "default": {
+                  "type": "string",
+                  "maxLength": 100000
+                }
+              },
+              "required": [
+                "name"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "returns": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "maxLength": 100000
+              },
+              "description": {
+                "type": "string",
+                "maxLength": 100000
+              }
+            },
+            "additionalProperties": false
+          },
+          "yields": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "maxLength": 100000
+              },
+              "description": {
+                "type": "string",
+                "maxLength": 100000
+              }
+            },
+            "additionalProperties": false
+          },
+          "raises": {
+            "maxItems": 1000,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 512
+                },
+                "type": {
+                  "type": "string",
+                  "maxLength": 100000
+                },
+                "description": {
+                  "type": "string",
+                  "maxLength": 100000
+                },
+                "default": {
+                  "type": "string",
+                  "maxLength": 100000
+                }
+              },
+              "required": [
+                "name"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "examples": {
+            "maxItems": 100,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "title": {
+                  "type": "string",
+                  "maxLength": 512
+                },
+                "code": {
+                  "type": "string",
+                  "maxLength": 100000
+                }
+              },
+              "required": [
+                "code"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "seeAlso": {
+            "maxItems": 1000,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[^\\s\\x00-\\x1f]+$"
+            }
+          },
+          "source": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 1000,
+                "pattern": "^(?!\\/)(?!.*(?:^|\\/)\\.{1,2}(?:\\/|$))[^/\\\\\\x00:]+(?:\\/[^/\\\\\\x00:]+)*$"
+              },
+              "line": {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
+              }
+            },
+            "required": [
+              "path"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "kind",
+          "visibility"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "kind",
+    "programmingLanguage",
+    "producer",
+    "symbols"
+  ],
+  "additionalProperties": false,
+  "title": "Shoalrun Code API reference snapshot"
+}

package/skills/shoalrun-author/SKILL.md

@@ -21,6 +21,10 @@ When reading a published site through Markdown, follow topic-index links when pr
 
 Read `reference.authoring-workspace` for tool contracts and `guide.authoring-workspace` for the working-tree procedure. Before unfamiliar syntax, check the relevant component attributes, configuration structure, or asset-handling contract instead of assuming another tool’s conventions. For MDX components, read their canonical reference; `<Step>` belongs inside `<Steps>` for an ordinary titled procedure, while your harness's task plan is separate. Read implementation/specification evidence with your harness's permitted tools; record the sources for changed claims. Bundled guidance does not establish a consumer project's facts.
 
+## Code API references
+
+For source-code library or SDK references, read [references/code-api-references.md](references/code-api-references.md). Keep these separate from OpenAPI endpoint references. Extract explicitly, validate the snapshot, preserve publication and feature scope, and choose symbol, class, module, or optional complete-page presentation deliberately.
+
 ## Products and availability
 
 For independently versioned products, cross-product reuse, product-scoped delivery, or feature availability labels, read [references/publications.md](references/publications.md). Preserve product/channel/version/language identity, distinguish publication membership from feature grants, and check installed-version support before using new fields. Availability labels describe support; they don't filter the published content.

package/skills/shoalrun-author/references/code-api-references.md

@@ -0,0 +1,15 @@
+# Code API reference authoring
+
+Read `guide.code-api-references` and `reference.code-api-references` from the installed package's bundled docs when present. Check installed-version support; the feature starts in 1.0.0. A source checkout also provides `CODE-REFERENCES.md` and a runnable `examples/code-references` project.
+
+Use `codeReferences` for a language library or SDK, and `apis` for OpenAPI HTTP endpoints. A converter writes the versioned snapshot; normal builds never invoke it. The optional Python adapter requires an explicitly prepared Python 3.11+ environment with its pinned requirements. Keep extraction roots narrow and don't enable runtime inspection or external discovery to make an unsupported package appear to work. Other languages can provide their own converter; don't claim a bundled Kotlin extractor.
+
+Run `shoalrun references check FILE`, inspect the snapshot's public symbols and prose, then configure the catalog. Snapshot descriptions are inert Markdown; MDX, project directives, relative links, and images aren't supported. Preserve exact symbol IDs and use explicit document IDs/slugs when public identities must survive a rename. Keep snapshots in the project and regenerate them after source changes.
+
+Choose `layout: symbols`, `classes`, or `modules` by reading needs. All retain individual symbol URLs. Add `singlePage` only when a complete reference is useful; configure its ID, slug, title, summary, and optional metadata, then link that ID in navigation. Group class or module pages in navigation instead of listing every symbol when a shorter menu is wanted.
+
+Preserve product/channel/version/language source bindings. Catalog and symbol metadata classify their content; a parent's feature requirements aren't inherited by children. Strict source classification also applies to the complete page. Pass the same profile through validation, build, and export. Check that private, restricted, or audience-excluded symbols don't reappear inside grouped or complete pages.
+
+Type links use explicit converter targets and remain within eligible catalog/publication scope. Keep unknown types unlinked. Required fields are distinct from nullable fields; show defaults as unevaluated expressions. Configure repository source links only with a real HTTPS base directory and intended release/commit; never invent a repository location.
+
+Review class/module and complete pages in HTML and Markdown. Check inline symbol links, retained individual URLs, narrow-screen table scrolling and keyboard focus, and content-export/PDF selection by ID where relevant. Reading references doesn't require JavaScript; Copy controls do. Extraction doesn't prove runtime behavior or execute examples.

package/styles/site.css

@@ -167,7 +167,7 @@ button{cursor:pointer}
 /* Reading rhythm for overviews, guides, and reference prose. */
 .content{grid-area:main;min-width:0;max-width:68rem;overflow-wrap:anywhere}
 .eyebrow{font-size:.7rem;font-weight:700;text-transform:uppercase;letter-spacing:.13em;color:var(--color-emphasis)}
-.page-head{padding-bottom:2rem;margin-bottom:2rem;border-bottom:1px solid var(--color-border)}
+.page-head{padding-bottom:.75rem;margin-bottom:.65rem;border-bottom:1px solid var(--color-border)}
 .content[data-document-type=cookbook] .page-head{padding:1.45rem 1.6rem;margin-bottom:1.8rem;border:1px solid var(--color-border);border-top:4px solid var(--color-accent);border-radius:var(--radius-panel);background:var(--color-field-surface)}
 .content[data-document-type=cookbook] .page-head .eyebrow{display:inline-block;padding:.28rem .55rem;border:1px solid var(--color-border);border-radius:999px;background:var(--color-surface)}
 .content[data-document-type=cookbook] .page-head h1{margin:.8rem 0 .8rem}
@@ -182,6 +182,7 @@ button{cursor:pointer}
 .audience-labels{display:flex;align-items:center;flex-wrap:wrap;gap:.4rem;margin:-.25rem 0 1.25rem;font-size:.78rem}
 .audience-label-heading{font-weight:650;color:var(--color-muted);margin-right:.1rem}
 .audience-badge{padding:.2rem .55rem;border:1px solid var(--color-border);border-radius:999px;background:var(--color-surface);color:var(--color-ink);font-weight:600;line-height:1.4;overflow-wrap:anywhere}
+.page-head>:last-child{margin-bottom:0}
 .formats{display:inline-flex;align-items:center;min-height:2.5rem;font-size:.78rem;font-weight:600;color:var(--color-muted);text-decoration:none;border:1px solid transparent;border-radius:var(--radius-small);padding:.35rem .6rem;margin-left:-.6rem}
 .formats:hover{color:var(--color-link-hover);background:var(--color-nav-hover)}
 .endpoint-route{display:flex;align-items:center;flex-wrap:wrap;gap:.65rem;margin:1.35rem 0 1rem;padding:.65rem .8rem;border:1px solid var(--color-border);border-radius:var(--radius-small);background:var(--color-field-surface);min-width:0}
@@ -489,7 +490,7 @@ button{cursor:pointer}
   .mast-inner{padding:.9rem 1.1rem;gap:.65rem}
   .brand{font-size:.9rem}
   .edition{font-size:.65rem}
-  .page-head{padding-bottom:1.5rem;margin-bottom:1.5rem}
+  .page-head{padding-bottom:.75rem;margin-bottom:.65rem}
   .page-head h1{font-size:2.1rem}
   .content .summary{font-size:1rem}
   .content h2{font-size:1.3rem;margin-top:2rem}
@@ -835,3 +836,61 @@ button[data-copy-markdown][hidden]{display:none}
 .content .doc-image-align-left{display:block;margin-left:0;margin-right:auto}
 .content .doc-image-align-center{display:block;margin-left:auto;margin-right:auto}
 .content .doc-image-align-right{display:block;margin-left:auto;margin-right:0}
+
+/* Code API references share one type scale across prose, declarations and tables. */
+.content[data-document-type=code-reference]{--reference-text:.9375rem;--reference-code:.875rem;--reference-small:.8125rem;font-size:var(--reference-text);line-height:1.65}
+.content[data-document-type=code-reference] .page-head h1{font-family:var(--font-code);font-size:clamp(1.75rem,2.2vw,2.25rem);letter-spacing:-.035em;line-height:1.2;overflow-wrap:anywhere}
+.content[data-document-type=code-reference] .summary{font-size:var(--reference-text);line-height:1.65;max-width:68ch}
+.content[data-document-type=code-reference] .eyebrow{font-size:var(--reference-small)}
+.content[data-document-type=code-reference] .page-formats{margin-bottom:1rem}
+.content[data-document-type=code-reference] .formats{font-size:var(--reference-small)}
+.content[data-document-type=code-reference] article p{font-size:inherit;line-height:1.65;margin:.75rem 0 1rem}
+.content[data-document-type=code-reference] article>h2{font-size:1.25rem;line-height:1.35;letter-spacing:-.025em;margin:1.75rem 0 .85rem;padding-top:1rem}
+.content[data-document-type=code-reference] article h3{font-size:1rem;line-height:1.4;margin:1.4rem 0 .65rem}
+.content[data-document-type=code-reference] article :is(h4,h5){font-size:var(--reference-text);line-height:1.4}
+.content[data-document-type=code-reference] article code{font-size:var(--reference-code)}
+.content[data-document-type=code-reference] .code-reference-identity{display:flex;align-items:baseline;flex-wrap:wrap;gap:.65rem;font-size:var(--reference-small);color:var(--color-muted);margin:.35rem 0 .65rem}
+.content[data-document-type=code-reference] .code-reference-identity strong{font-size:inherit;text-transform:none;letter-spacing:0;font-weight:600;color:var(--color-emphasis)}
+.content[data-document-type=code-reference] .code-reference-identity code{background:none;padding:0;color:inherit;max-width:100%;overflow-wrap:anywhere}
+.content[data-document-type=code-reference] .code-reference-identity a{text-decoration:none}
+.content[data-document-type=code-reference] .code-reference-identity a:hover{text-decoration:underline}
+.content[data-document-type=code-reference] .code-block:has(code.code-reference-signature){display:grid;grid-template-columns:minmax(0,1fr) auto;position:relative;margin:.65rem 0 1rem;box-shadow:none;background:var(--color-field-surface);border:1px solid var(--color-border);border-radius:var(--radius-small)}
+.content[data-document-type=code-reference] pre:has(>code.code-reference-signature){grid-column:1;grid-row:1;min-width:0;padding:.85rem 1rem;font-size:var(--reference-code);line-height:1.65;white-space:pre-wrap;overflow-wrap:anywhere;background:var(--color-field-surface)!important;color:var(--color-ink)!important}
+.code-block:has(code.code-reference-signature)>.code-toolbar{grid-column:2;grid-row:1;align-self:start;min-height:0;height:auto;padding:.45rem .4rem 0 0;border:0}
+.code-block:has(code.code-reference-signature)>.code-toolbar>:not(.code-copy){display:none}
+.code-block:has(code.code-reference-signature)>.code-toolbar>.code-copy{position:static;min-height:2rem;font-size:var(--reference-small)}
+.content[data-document-type=code-reference] code.code-reference-signature,.content[data-document-type=code-reference] code.code-reference-signature span{color:var(--color-ink)!important;font-weight:400;white-space:inherit;overflow-wrap:inherit}
+.content[data-document-type=code-reference] .code-block:has(code.code-reference-signature) .code-copy{color:var(--color-muted)}
+.content[data-document-type=code-reference] .code-block:has(code.code-reference-signature) .code-copy:hover{color:var(--color-ink);background:var(--color-nav-hover);border-color:var(--color-border)}
+.content[data-document-type=code-reference] .code-block:has(code.code-reference-signature) .code-copy:focus-visible{outline-color:var(--color-accent)}
+.content[data-document-type=code-reference] table.code-reference-table{table-layout:auto;font-size:var(--reference-text);line-height:1.65;margin:.75rem 0 1.25rem}
+.content[data-document-type=code-reference] .code-reference-table th{font-size:var(--reference-small);text-transform:none;letter-spacing:0;background:transparent;color:var(--color-muted);font-weight:600;border-bottom:1px solid var(--color-border)}
+.content[data-document-type=code-reference] .code-reference-table :is(th,td){padding:.65rem .6rem;overflow-wrap:normal}
+.content[data-document-type=code-reference] .code-reference-table td{font-size:var(--reference-text)}
+.content[data-document-type=code-reference] .code-reference-table td:first-child{width:22%;font-weight:500}
+.content[data-document-type=code-reference] .code-reference-table td:nth-child(2){width:26%;color:var(--color-muted)}
+.content[data-document-type=code-reference] .code-reference-table td:last-child{min-width:12rem}
+.content[data-document-type=code-reference] .code-reference-table code{font-size:var(--reference-code);overflow-wrap:normal;background:none;padding:0}
+.content[data-document-type=code-reference] .code-reference-table a{font-weight:600;text-decoration:none}
+.content[data-document-type=code-reference] .code-reference-table a code{color:var(--color-link)}
+.content[data-document-type=code-reference] .code-reference-table a:hover{text-decoration:underline}
+.content[data-document-type=code-reference] .code-reference-table tbody tr:hover{background:var(--color-field-surface)}
+.content[data-document-type=code-reference] .code-reference-table:has(th:nth-child(4)) td:first-child{width:18%}
+.content[data-document-type=code-reference] .code-reference-table:has(th:nth-child(4)) td:nth-child(2){width:23%}
+.content[data-document-type=code-reference] .code-reference-table:has(th:nth-child(4)) td:nth-child(3){width:22%;color:var(--color-muted)}
+.content[data-document-type=code-reference] .code-reference-summary{display:none}
+.content[data-document-type=code-reference] .code-reference-table-scroll{max-width:100%;min-width:0;overflow-x:auto;margin:.75rem 0 1.25rem;scrollbar-width:thin}
+.content[data-document-type=code-reference] .code-reference-table-scroll:focus-visible{outline:2px solid var(--color-accent);outline-offset:3px}
+.content[data-document-type=code-reference] .code-reference-table-scroll table{min-width:38rem;margin:0}
+.content[data-document-type=code-reference] .code-reference-table-scroll table:has(th:nth-child(4)){min-width:46rem}
+@media print{
+  .content[data-document-type=code-reference] .code-reference-table-scroll{overflow:visible}
+  .content[data-document-type=code-reference] .code-reference-table-scroll table,.content[data-document-type=code-reference] .code-reference-table-scroll table:has(th:nth-child(4)){min-width:0;table-layout:fixed}
+  .content[data-document-type=code-reference] .code-reference-table-scroll :is(th,td,code){overflow-wrap:anywhere;min-width:0}
+}
+@media(max-width:48rem){
+  .content[data-document-type=code-reference] .page-head h1{font-size:1.75rem}
+  .content[data-document-type=code-reference] table.code-reference-table{table-layout:auto}
+  .content[data-document-type=code-reference] .code-reference-table :is(th,td){padding:.55rem .3rem}
+  .content[data-document-type=code-reference] .code-reference-table td:last-child{min-width:14rem}
+}