@timeax/scaffold 0.0.3 → 0.0.5

package/dist/ast.d.cts

@@ -0,0 +1,152 @@
+type AstMode = 'strict' | 'loose';
+type DiagnosticSeverity = 'info' | 'warning' | 'error';
+interface Diagnostic {
+    line: number;
+    column?: number;
+    message: string;
+    severity: DiagnosticSeverity;
+    code?: string;
+}
+/**
+ * How a physical line in the text was classified.
+ */
+type LineKind = 'blank' | 'comment' | 'entry';
+interface StructureAstLine {
+    index: number;
+    lineNo: number;
+    raw: string;
+    kind: LineKind;
+    indentSpaces: number;
+    content: string;
+}
+/**
+ * AST node base for structure entries.
+ */
+interface AstNodeBase {
+    type: 'dir' | 'file';
+    /** The last segment name, e.g. "schema/" or "index.ts". */
+    name: string;
+    /** Depth level (0 = root, 1 = child of root, etc.). */
+    depth: number;
+    /** 1-based source line number. */
+    line: number;
+    /** Normalized POSIX path from root, e.g. "src/schema/index.ts" or "src/schema/". */
+    path: string;
+    /** Stub annotation, if any. */
+    stub?: string;
+    /** Include glob patterns, if any. */
+    include?: string[];
+    /** Exclude glob patterns, if any. */
+    exclude?: string[];
+    /** Parent node; null for roots. */
+    parent: DirNode | null;
+}
+interface DirNode extends AstNodeBase {
+    type: 'dir';
+    children: AstNode[];
+}
+interface FileNode extends AstNodeBase {
+    type: 'file';
+    children?: undefined;
+}
+type AstNode = DirNode | FileNode;
+interface AstOptions {
+    /**
+     * Spaces per indent level.
+     * Default: 2.
+     */
+    indentStep?: number;
+    /**
+     * Parser mode:
+     * - "strict": mismatched indentation / impossible structures are errors.
+     * - "loose" : tries to recover from bad indentation, demotes some issues to warnings.
+     *
+     * Default: "loose".
+     */
+    mode?: AstMode;
+}
+/**
+ * Full AST result: nodes + per-line meta + diagnostics.
+ */
+interface StructureAst {
+    /** Root-level nodes (depth 0). */
+    rootNodes: AstNode[];
+    /** All lines as seen in the source file. */
+    lines: StructureAstLine[];
+    /** Collected diagnostics (errors + warnings + infos). */
+    diagnostics: Diagnostic[];
+    /** Resolved options used by the parser. */
+    options: Required<AstOptions>;
+}
+/**
+ * Main entry: parse a structure text into an AST tree with diagnostics.
+ *
+ * - Does NOT throw on parse errors.
+ * - Always returns something (even if diagnostics contain errors).
+ * - In "loose" mode, attempts to repair:
+ *   - odd/misaligned indentation → snapped via relative depth rules with warnings.
+ *   - large indent jumps → treated as "one level deeper" with warnings.
+ *   - children under files → attached to nearest viable ancestor with warnings.
+ */
+declare function parseStructureAst(text: string, opts?: AstOptions): StructureAst;
+declare function mapThrough(content: string): number;
+/**
+ * Extracts the inline comment portion (if any) from the content area (no leading indent).
+ */
+declare function extractInlineCommentParts(content: string): {
+    contentWithoutComment: string;
+    inlineComment: string | null;
+};
+
+interface FormatOptions {
+    /**
+     * Spaces per indent level for re-printing entries.
+     * Defaults to 2.
+     */
+    indentStep?: number;
+    /**
+     * Parser mode to use for the AST.
+     * - "loose": attempt to repair mis-indents / bad parents (default).
+     * - "strict": report issues as errors, less repair.
+     */
+    mode?: AstMode;
+    /**
+     * Normalize newlines to the dominant style in the original text (LF vs CRLF).
+     * Defaults to true.
+     */
+    normalizeNewlines?: boolean;
+    /**
+     * Trim trailing whitespace on non-entry lines (comments / blanks).
+     * Defaults to true.
+     */
+    trimTrailingWhitespace?: boolean;
+    /**
+     * Whether to normalize annotation ordering and spacing:
+     *   name @stub:... @include:... @exclude:...
+     * Defaults to true.
+     */
+    normalizeAnnotations?: boolean;
+}
+interface FormatResult {
+    /** Formatted text. */
+    text: string;
+    /** Underlying AST that was used. */
+    ast: StructureAst;
+}
+/**
+ * Smart formatter for scaffold structure files.
+ *
+ * - Uses the loose AST parser (parseStructureAst) to understand structure.
+ * - Auto-fixes indentation based on tree depth (indentStep).
+ * - Keeps **all** blank lines and full-line comments in place.
+ * - Preserves inline comments (# / //) on entry lines.
+ * - Canonicalizes annotation order (stub → include → exclude) if enabled.
+ *
+ * It does **not** throw on invalid input:
+ * - parseStructureAst always returns an AST + diagnostics.
+ * - If something is catastrophically off (entry/node counts mismatch),
+ *   it falls back to a minimal normalization pass.
+ */
+declare function formatStructureText(text: string, options?: FormatOptions): FormatResult;
+
+export { type AstMode, type AstNode, type AstOptions, type Diagnostic, type DiagnosticSeverity, type DirNode, type FileNode, type FormatOptions, type FormatResult, type LineKind, type StructureAst, type StructureAstLine, extractInlineCommentParts, formatStructureText, mapThrough, parseStructureAst };

package/dist/ast.d.ts

@@ -0,0 +1,152 @@
+type AstMode = 'strict' | 'loose';
+type DiagnosticSeverity = 'info' | 'warning' | 'error';
+interface Diagnostic {
+    line: number;
+    column?: number;
+    message: string;
+    severity: DiagnosticSeverity;
+    code?: string;
+}
+/**
+ * How a physical line in the text was classified.
+ */
+type LineKind = 'blank' | 'comment' | 'entry';
+interface StructureAstLine {
+    index: number;
+    lineNo: number;
+    raw: string;
+    kind: LineKind;
+    indentSpaces: number;
+    content: string;
+}
+/**
+ * AST node base for structure entries.
+ */
+interface AstNodeBase {
+    type: 'dir' | 'file';
+    /** The last segment name, e.g. "schema/" or "index.ts". */
+    name: string;
+    /** Depth level (0 = root, 1 = child of root, etc.). */
+    depth: number;
+    /** 1-based source line number. */
+    line: number;
+    /** Normalized POSIX path from root, e.g. "src/schema/index.ts" or "src/schema/". */
+    path: string;
+    /** Stub annotation, if any. */
+    stub?: string;
+    /** Include glob patterns, if any. */
+    include?: string[];
+    /** Exclude glob patterns, if any. */
+    exclude?: string[];
+    /** Parent node; null for roots. */
+    parent: DirNode | null;
+}
+interface DirNode extends AstNodeBase {
+    type: 'dir';
+    children: AstNode[];
+}
+interface FileNode extends AstNodeBase {
+    type: 'file';
+    children?: undefined;
+}
+type AstNode = DirNode | FileNode;
+interface AstOptions {
+    /**
+     * Spaces per indent level.
+     * Default: 2.
+     */
+    indentStep?: number;
+    /**
+     * Parser mode:
+     * - "strict": mismatched indentation / impossible structures are errors.
+     * - "loose" : tries to recover from bad indentation, demotes some issues to warnings.
+     *
+     * Default: "loose".
+     */
+    mode?: AstMode;
+}
+/**
+ * Full AST result: nodes + per-line meta + diagnostics.
+ */
+interface StructureAst {
+    /** Root-level nodes (depth 0). */
+    rootNodes: AstNode[];
+    /** All lines as seen in the source file. */
+    lines: StructureAstLine[];
+    /** Collected diagnostics (errors + warnings + infos). */
+    diagnostics: Diagnostic[];
+    /** Resolved options used by the parser. */
+    options: Required<AstOptions>;
+}
+/**
+ * Main entry: parse a structure text into an AST tree with diagnostics.
+ *
+ * - Does NOT throw on parse errors.
+ * - Always returns something (even if diagnostics contain errors).
+ * - In "loose" mode, attempts to repair:
+ *   - odd/misaligned indentation → snapped via relative depth rules with warnings.
+ *   - large indent jumps → treated as "one level deeper" with warnings.
+ *   - children under files → attached to nearest viable ancestor with warnings.
+ */
+declare function parseStructureAst(text: string, opts?: AstOptions): StructureAst;
+declare function mapThrough(content: string): number;
+/**
+ * Extracts the inline comment portion (if any) from the content area (no leading indent).
+ */
+declare function extractInlineCommentParts(content: string): {
+    contentWithoutComment: string;
+    inlineComment: string | null;
+};
+
+interface FormatOptions {
+    /**
+     * Spaces per indent level for re-printing entries.
+     * Defaults to 2.
+     */
+    indentStep?: number;
+    /**
+     * Parser mode to use for the AST.
+     * - "loose": attempt to repair mis-indents / bad parents (default).
+     * - "strict": report issues as errors, less repair.
+     */
+    mode?: AstMode;
+    /**
+     * Normalize newlines to the dominant style in the original text (LF vs CRLF).
+     * Defaults to true.
+     */
+    normalizeNewlines?: boolean;
+    /**
+     * Trim trailing whitespace on non-entry lines (comments / blanks).
+     * Defaults to true.
+     */
+    trimTrailingWhitespace?: boolean;
+    /**
+     * Whether to normalize annotation ordering and spacing:
+     *   name @stub:... @include:... @exclude:...
+     * Defaults to true.
+     */
+    normalizeAnnotations?: boolean;
+}
+interface FormatResult {
+    /** Formatted text. */
+    text: string;
+    /** Underlying AST that was used. */
+    ast: StructureAst;
+}
+/**
+ * Smart formatter for scaffold structure files.
+ *
+ * - Uses the loose AST parser (parseStructureAst) to understand structure.
+ * - Auto-fixes indentation based on tree depth (indentStep).
+ * - Keeps **all** blank lines and full-line comments in place.
+ * - Preserves inline comments (# / //) on entry lines.
+ * - Canonicalizes annotation order (stub → include → exclude) if enabled.
+ *
+ * It does **not** throw on invalid input:
+ * - parseStructureAst always returns an AST + diagnostics.
+ * - If something is catastrophically off (entry/node counts mismatch),
+ *   it falls back to a minimal normalization pass.
+ */
+declare function formatStructureText(text: string, options?: FormatOptions): FormatResult;
+
+export { type AstMode, type AstNode, type AstOptions, type Diagnostic, type DiagnosticSeverity, type DirNode, type FileNode, type FormatOptions, type FormatResult, type LineKind, type StructureAst, type StructureAstLine, extractInlineCommentParts, formatStructureText, mapThrough, parseStructureAst };