sveld 0.31.0 → 0.32.1

package/README.md

@@ -127,6 +127,7 @@ export default class Button extends SvelteComponentTyped<
   - [CLI](#cli)
   - [Publishing to NPM](#publishing-to-npm)
 - [Available Options](#available-options)
+- [JSON Output](#json-output)
 - [API Reference](#api-reference)
   - [@type](#type)
   - [@default](#default)
@@ -333,6 +334,121 @@ sveld({
 })
 ```
 
+## JSON Output
+
+When `json: true` is enabled, `sveld` emits a `COMPONENT_API.json` file with schema and generator metadata plus the parsed
+component API.
+
+The public JSON Schema for the combined output is hosted on GitHub ([path to file](https://github.com/carbon-design-system/sveld/blob/main/schema/component-api.schema.json), [raw URL](https://raw.githubusercontent.com/carbon-design-system/sveld/main/schema/component-api.schema.json)). Use it to document or validate
+generated `COMPONENT_API.json` files. The schema describes the emitted metadata contract; optional fields may be absent when
+the parser does not have a stable source for that metadata.
+
+```ts
+interface ComponentApiJson {
+  schemaVersion: 1;
+  generator: {
+    name: string;
+    version: string;
+    svelteVersion: string;
+  };
+  total: number;
+  components: ComponentDocApi[];
+}
+
+interface SourceRange {
+  start: SourcePosition;
+  end: SourcePosition;
+}
+
+interface SourcePosition {
+  line: number;
+  column: number;
+}
+
+interface ComponentDocApi {
+  moduleName: string;
+  filePath: string;
+  source?: SourceRange;
+  syntaxMode: "legacy" | "runes";
+  scriptLanguage?: "js" | "ts";
+  props: ComponentProp[];
+  moduleExports: ComponentProp[];
+  slots: ComponentSlot[];
+  events: ComponentEvent[];
+  typedefs: TypeDef[];
+  generics: null | [name: string, type: string];
+  rest_props?: RestProps;
+  extends?: { interface: string; import: string };
+  componentComment?: string;
+  componentCommentSource?: SourceRange;
+  contexts?: ComponentContext[];
+}
+
+interface ComponentProp {
+  name: string;
+  localName?: string;
+  kind: "let" | "const" | "function";
+  constant: boolean;
+  type?: string;
+  typeSource?: "typescript" | "jsdoc" | "default" | "inferred" | "unknown";
+  value?: string;
+  defaultValue?: {
+    raw: string;
+    kind: "literal" | "array" | "object" | "expression" | "function" | "unknown";
+    value?: unknown;
+  };
+  description?: string;
+  params?: Array<{ name: string; type: string; description?: string; optional?: boolean }>;
+  returnType?: string;
+  isFunction: boolean;
+  isFunctionDeclaration: boolean;
+  isRequired: boolean;
+  reactive: boolean;
+  binding?: "readonly" | "writable";
+  bindable?: true;
+  source?: SourceRange;
+}
+
+interface ComponentSlot {
+  name?: string | null;
+  default: boolean;
+  fallback?: string;
+  slot_props?: string;
+  description?: string;
+  tags?: Array<{ name: string; body: string }>;
+  source?: SourceRange;
+}
+
+type ComponentEvent =
+  | {
+      type: "forwarded";
+      name: string;
+      element: string;
+      description?: string;
+      detail?: string;
+      source?: SourceRange;
+    }
+  | {
+      type: "dispatched";
+      name: string;
+      detail?: string;
+      description?: string;
+      source?: SourceRange;
+    };
+```
+
+`source` fields are optional and are included only when the Svelte or JavaScript AST provides stable positions. They do not
+include source text or raw character offsets.
+
+Note that `SourcePosition.line` is 1-based and `SourcePosition.column` is 0-based.
+
+Prop metadata is additive and preserves the older public fields:
+
+- `name` is always the public prop name. For runes `$props()` aliases such as `let { class: className } = $props()`, `localName` is emitted only when the local binding differs.
+- `typeSource` identifies the conservative source of the emitted `type`: TypeScript annotation, JSDoc, initializer/default inference, other parser inference, or unknown fallback.
+- `value` remains the raw default expression string. `defaultValue` adds structured metadata with the same raw expression, a coarse `kind`, and a parsed `value` only for JSON-safe literals, arrays, and plain objects. `sveld` does not evaluate arbitrary code.
+- `bindable: true` is emitted only for props explicitly declared with Svelte 5 `$bindable(...)`. Missing `bindable` should be treated as false.
+
 ## API Reference
 
 ### `reactive`
@@ -350,6 +466,38 @@ Local variables or parameters that shadow a prop name do not count as writes to
 
 `reactive: false` means `sveld` found no such evidence. It does not imply that parent-side `bind:` usage is impossible.
 
+### `binding`
+
+The optional `binding` field in generated JSON is explicit documentation metadata for a prop's intended `bind:` contract. It is separate from `reactive`, and it is never inferred from internal writes or `$bindable()`.
+
+Use `@bindable readonly` for component-owned or output-style bindings where the consumer binds to the current value emitted by the component:
+
+```svelte
+<script>
+  /**
+   * Bind to the current value emitted by the component.
+   * @bindable readonly
+   */
+  export let size = undefined;
+</script>
+```
+
+Use `@bindable writable` for two-way or shared state bindings where either the consumer or component may control the value:
+
+```svelte
+<script>
+  /**
+   * Bind to state controlled by either the consumer or component.
+   * @bindable writable
+   */
+  export let open = false;
+</script>
+```
+
+Generated JSON includes `"binding": "readonly"` or `"binding": "writable"` for annotated props. Unannotated props omit the field.
+
+This is documentation metadata only. Generated `.svelte.d.ts` prop types are unchanged because TypeScript cannot reliably express Svelte component binding direction.
+
 For stable output, generated `events` arrays are emitted in deterministic sorted order.
 
 ### `@type`

package/lib/ComponentParser.d.ts

@@ -1,3 +1,13 @@
+export interface SourcePosition {
+    /** 1-based source line number */
+    line: number;
+    /** 0-based source column number */
+    column: number;
+}
+export interface SourceRange {
+    start: SourcePosition;
+    end: SourcePosition;
+}
 export interface ParsedComponentTypeScriptMetadata {
     canonicalPropsType?: string;
     canonicalPropNames: string[];
@@ -8,6 +18,15 @@ export declare const PARSED_COMPONENT_TYPE_SCRIPT_METADATA: unique symbol;
 export declare function getParsedComponentTypeScriptMetadata(component: {
     [PARSED_COMPONENT_TYPE_SCRIPT_METADATA]?: ParsedComponentTypeScriptMetadata;
 }): ParsedComponentTypeScriptMetadata | undefined;
+type SyntaxMode = "legacy" | "runes";
+type ScriptLanguage = "js" | "ts";
+type ComponentPropTypeSource = "typescript" | "jsdoc" | "default" | "inferred" | "unknown";
+type ComponentPropDefaultValueKind = "literal" | "array" | "object" | "expression" | "function" | "unknown";
+interface ComponentPropDefaultValue {
+    raw: string;
+    kind: ComponentPropDefaultValueKind;
+    value?: unknown;
+}
 /**
  * Diagnostic information for component parsing.
  *
@@ -27,6 +46,7 @@ interface ComponentParserOptions {
     /** Enable verbose logging for debugging parsing issues */
     verbose?: boolean;
 }
+type ComponentPropBinding = "readonly" | "writable";
 /**
  * Parameter information for function props.
  *
@@ -58,8 +78,14 @@ interface ComponentProp {
     constant: boolean;
     /** The TypeScript type of the prop (e.g., "string", "number | string") */
     type?: string;
+    /** Conservative provenance for the prop type */
+    typeSource?: ComponentPropTypeSource;
+    /** Local variable name, emitted when it differs from the public prop name */
+    localName?: string;
     /** The default value as a string representation of the source code */
     value?: string;
+    /** Structured default value metadata for docs UIs */
+    defaultValue?: ComponentPropDefaultValue;
     /** Description extracted from JSDoc comments */
     description?: string;
     /** Function parameters (for function props) extracted from `@param` tags */
@@ -74,6 +100,12 @@ interface ComponentProp {
     isRequired: boolean;
     /** Whether this prop is reactive (can change and trigger reactivity) */
     reactive: boolean;
+    /** Explicit author-documented binding direction from `@bindable` JSDoc */
+    binding?: ComponentPropBinding;
+    /** True when the prop is explicitly declared with Svelte 5 `$bindable()` */
+    bindable?: true;
+    /** Source range for the prop declaration, when available */
+    source?: SourceRange;
 }
 /**
  * Component slot definition.
@@ -100,6 +132,8 @@ interface ComponentSlot {
         name: string;
         body: string;
     }>;
+    /** Source range for the slot/snippet declaration or documentation tag, when available */
+    source?: SourceRange;
 }
 /**
  * Event that is forwarded from a child component or element.
@@ -118,6 +152,8 @@ interface ForwardedEvent {
     description?: string;
     /** The detail type if explicitly specified in `@event` tag */
     detail?: string;
+    /** Source range for the forwarded event declaration or documentation tag, when available */
+    source?: SourceRange;
 }
 /**
  * Event that is dispatched by the component.
@@ -134,6 +170,8 @@ interface DispatchedEvent {
     detail?: string;
     /** Description extracted from JSDoc `@event` tags */
     description?: string;
+    /** Source range for the dispatched event call or documentation tag, when available */
+    source?: SourceRange;
 }
 type ComponentEvent = ForwardedEvent | DispatchedEvent;
 /**
@@ -256,6 +294,12 @@ interface ComponentContext {
  * ```
  */
 export interface ParsedComponent {
+    /** Source range for the component source that was parsed */
+    source?: SourceRange;
+    /** Whether the component uses legacy or runes syntax according to compiler metadata */
+    syntaxMode: SyntaxMode;
+    /** Language used by the instance or module script when it can be determined */
+    scriptLanguage?: ScriptLanguage;
     /** Component props that can be passed to the component */
     props: ComponentProp[];
     /** Exports from `<script context="module">` block */
@@ -274,6 +318,8 @@ export interface ParsedComponent {
     extends?: Extends;
     /** Component-level description from `@component` HTML comment */
     componentComment?: string;
+    /** Source range for the `@component` HTML comment, when available */
+    componentCommentSource?: SourceRange;
     /** Contexts created with `setContext` in the component */
     contexts?: ComponentContext[];
     /** Internal writer-only TypeScript metadata. Not serialized to JSON. */
@@ -284,6 +330,8 @@ export default class ComponentParser {
     private options?;
     /** Whether the component uses legacy or runes syntax according to compiler metadata */
     private syntaxMode;
+    /** Language used by the component's instance or module script, when supported */
+    private scriptLanguage?;
     /** Raw source code of the Svelte component being parsed */
     private source?;
     /** Compiled Svelte code containing extracted variables and AST */
@@ -296,6 +344,8 @@ export default class ComponentParser {
     private extends?;
     /** Component-level description extracted from `@component` HTML comment */
     private componentComment?;
+    /** Source range for the `@component` HTML comment, when available */
+    private componentCommentSource?;
     /** Set of reactive variable names found in the component */
     private readonly reactive_vars;
     /** Set of all variable declarations found in the component script */
@@ -348,8 +398,12 @@ export default class ComponentParser {
     private readonly activeScopes;
     /** Cached array of source code lines split by newline for efficient line-based operations */
     private sourceLinesCache?;
+    /** Cached 0-based source offsets for the start of each line */
+    private sourceLineStartOffsetsCache?;
     constructor(options?: ComponentParserOptions);
     private static mapToArray;
+    private static getStaticAttributeValue;
+    private static resolveScriptLanguage;
     private static assignValue;
     private resolvePublicPropName;
     private trackPropLocalName;
@@ -361,6 +415,11 @@ export default class ComponentParser {
     private getTypeReferenceName;
     private getTypeDependencyName;
     private getTypeAnnotationText;
+    private getSourceLineStartOffsets;
+    private sourcePositionFromOffset;
+    private sourceRangeFromOffsets;
+    private sourceRangeFromNode;
+    private sourceRangeFromCommentTag;
     private collectReferencedTypeDependencies;
     private buildTypeImportStatements;
     private buildTypeScriptMetadata;
@@ -384,6 +443,7 @@ export default class ComponentParser {
     private isCallExpressionNamed;
     private getPropertyName;
     private logUnsupportedRunesPattern;
+    private logParserWarning;
     private static formatComment;
     /**
      * Extracts and categorizes JSDoc tags from a parsed comment.
@@ -498,6 +558,10 @@ export default class ComponentParser {
      * @returns The source code substring, or undefined if source is not available
      */
     private sourceAtPos;
+    private sourceForExpression;
+    private jsonSafeValueFromExpression;
+    private classifyDefaultValue;
+    private resolveTypeSource;
     /**
      * Processes an initializer expression to extract its value, type, and function status.
      *