@galacean/engine-shader-parser 0.0.0-stage → 2.0.0-alpha.54

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (104) hide show
  1. package/LICENSE +21 -0
  2. package/dist/main.analyzer.js +2 -0
  3. package/dist/main.analyzer.js.map +1 -0
  4. package/dist/main.js +2 -0
  5. package/dist/main.js.map +1 -0
  6. package/dist/main.shared.js +2 -0
  7. package/dist/main.shared.js.map +1 -0
  8. package/dist/module.analyzer.js +2 -0
  9. package/dist/module.analyzer.js.map +1 -0
  10. package/dist/module.js +2 -0
  11. package/dist/module.js.map +1 -0
  12. package/dist/module.shared.js +2 -0
  13. package/dist/module.shared.js.map +1 -0
  14. package/dist/shared/GLESShaderInfo.main.js +2 -0
  15. package/dist/shared/GLESShaderInfo.main.js.map +1 -0
  16. package/dist/shared/GLESShaderInfo.module.js +2 -0
  17. package/dist/shared/GLESShaderInfo.module.js.map +1 -0
  18. package/internal/analyzer/package.json +5 -0
  19. package/internal/package.json +5 -0
  20. package/package.json +42 -3
  21. package/shared/package.json +5 -0
  22. package/types/GSError.d.ts +31 -0
  23. package/types/ParsedShaderPass.d.ts +11 -0
  24. package/types/ParserObjectPool.d.ts +51 -0
  25. package/types/ParserUtils.d.ts +91 -0
  26. package/types/Preprocessor.d.ts +71 -0
  27. package/types/PreprocessorExpression.d.ts +1 -0
  28. package/types/ShaderCompilerUtils.d.ts +9 -0
  29. package/types/backends/GLESShaderInfo.d.ts +39 -0
  30. package/types/common/BaseLexer.d.ts +61 -0
  31. package/types/common/BaseToken.d.ts +105 -0
  32. package/types/common/BranchAnalysis.d.ts +84 -0
  33. package/types/common/BranchIdentity.d.ts +58 -0
  34. package/types/common/BranchSemantics.d.ts +54 -0
  35. package/types/common/IBaseSymbol.d.ts +9 -0
  36. package/types/common/PreprocessorCondition.d.ts +39 -0
  37. package/types/common/ShaderPosition.d.ts +20 -0
  38. package/types/common/ShaderRange.d.ts +18 -0
  39. package/types/common/SymbolTable.d.ts +43 -0
  40. package/types/common/SymbolTableStack.d.ts +53 -0
  41. package/types/common/enums/Keyword.d.ts +124 -0
  42. package/types/common/enums/ShaderStage.d.ts +5 -0
  43. package/types/common/index.d.ts +5 -0
  44. package/types/common/types.d.ts +101 -0
  45. package/types/formatDiagnostic.d.ts +18 -0
  46. package/types/index.d.ts +37 -0
  47. package/types/ir/ShaderBuiltinSemantic.d.ts +13 -0
  48. package/types/ir/ShaderClueIR.d.ts +48 -0
  49. package/types/ir/ShaderCoreInfo.d.ts +85 -0
  50. package/types/ir/ShaderDeclarationOwnership.d.ts +36 -0
  51. package/types/ir/ShaderStructOwnership.d.ts +18 -0
  52. package/types/ir/index.d.ts +4 -0
  53. package/types/lalr/CFG.d.ts +5 -0
  54. package/types/lalr/LALR1.d.ts +27 -0
  55. package/types/lalr/Production.d.ts +9 -0
  56. package/types/lalr/State.d.ts +20 -0
  57. package/types/lalr/StateItem.d.ts +20 -0
  58. package/types/lalr/Utils.d.ts +29 -0
  59. package/types/lalr/index.d.ts +2 -0
  60. package/types/lalr/types.d.ts +14 -0
  61. package/types/lexer/AnalyzerLexer.d.ts +56 -0
  62. package/types/lexer/Lexer.d.ts +122 -0
  63. package/types/lexer/index.d.ts +1 -0
  64. package/types/parser/AST.d.ts +625 -0
  65. package/types/parser/AnalyzerSemanticDiagnostics.d.ts +15 -0
  66. package/types/parser/Grammar.d.ts +11 -0
  67. package/types/parser/GrammarSymbol.d.ts +128 -0
  68. package/types/parser/ICodeGenVisitor.d.ts +29 -0
  69. package/types/parser/MacroExpansionFacts.d.ts +25 -0
  70. package/types/parser/ParsedShaderPass.d.ts +71 -0
  71. package/types/parser/ParsedShaderPassHandle.d.ts +29 -0
  72. package/types/parser/ParserSemanticValidation.d.ts +110 -0
  73. package/types/parser/PassParser.d.ts +15 -0
  74. package/types/parser/RuntimePassParser.d.ts +24 -0
  75. package/types/parser/SemanticAnalyzer.d.ts +174 -0
  76. package/types/parser/SemanticDiagnostics.d.ts +93 -0
  77. package/types/parser/ShaderIncludePath.d.ts +23 -0
  78. package/types/parser/ShaderInfo.d.ts +56 -0
  79. package/types/parser/ShaderTargetParser.d.ts +65 -0
  80. package/types/parser/TypeSystem.d.ts +104 -0
  81. package/types/parser/ValidatedPassParser.d.ts +24 -0
  82. package/types/parser/builtin/functions.d.ts +34 -0
  83. package/types/parser/builtin/index.d.ts +2 -0
  84. package/types/parser/builtin/variables.d.ts +13 -0
  85. package/types/parser/index.d.ts +7 -0
  86. package/types/parser/symbolTable/FnSymbol.d.ts +9 -0
  87. package/types/parser/symbolTable/StructSymbol.d.ts +6 -0
  88. package/types/parser/symbolTable/SymbolDataType.d.ts +12 -0
  89. package/types/parser/symbolTable/SymbolInfo.d.ts +33 -0
  90. package/types/parser/symbolTable/VarSymbol.d.ts +16 -0
  91. package/types/parser/symbolTable/index.d.ts +6 -0
  92. package/types/parser/types.d.ts +49 -0
  93. package/types/preprocessor/PreprocessorCondition.d.ts +56 -0
  94. package/types/preprocessor/PreprocessorConditionDiagram.d.ts +11 -0
  95. package/types/preprocessor/PreprocessorConditionNormalization.d.ts +18 -0
  96. package/types/preprocessor/PreprocessorMacroState.d.ts +84 -0
  97. package/types/runtime.d.ts +36 -0
  98. package/types/shared.d.ts +1 -0
  99. package/types/sourceParser/ShaderSourceFactory.d.ts +8 -0
  100. package/types/sourceParser/ShaderSourceParser.d.ts +36 -0
  101. package/types/sourceParser/ShaderSourceSymbol.d.ts +12 -0
  102. package/types/sourceParser/SourceLexer.d.ts +20 -0
  103. package/types/sourceParser/index.d.ts +1 -0
  104. package/README.md +0 -3
@@ -0,0 +1,5 @@
1
+ {
2
+ "main": "../../dist/main.analyzer.js",
3
+ "module": "../../dist/module.analyzer.js",
4
+ "types": "../../types/index.d.ts"
5
+ }
@@ -0,0 +1,5 @@
1
+ {
2
+ "main": "../dist/main.js",
3
+ "module": "../dist/module.js",
4
+ "types": "../types/runtime.d.ts"
5
+ }
package/package.json CHANGED
@@ -1,6 +1,45 @@
1
1
  {
2
2
  "name": "@galacean/engine-shader-parser",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "2.0.0-alpha.54",
4
+ "publishConfig": {
5
+ "access": "public",
6
+ "registry": "https://registry.npmjs.org"
7
+ },
8
+ "repository": {
9
+ "url": "https://github.com/galacean/engine.git"
10
+ },
11
+ "license": "MIT",
12
+ "exports": {
13
+ "./internal": {
14
+ "types": "./types/runtime.d.ts",
15
+ "import": "./dist/module.js",
16
+ "require": "./dist/main.js"
17
+ },
18
+ "./internal/analyzer": {
19
+ "types": "./types/index.d.ts",
20
+ "import": "./dist/module.analyzer.js",
21
+ "require": "./dist/main.analyzer.js"
22
+ },
23
+ "./shared": {
24
+ "types": "./types/shared.d.ts",
25
+ "import": "./dist/module.shared.js",
26
+ "require": "./dist/main.shared.js"
27
+ },
28
+ "./package.json": "./package.json"
29
+ },
30
+ "files": [
31
+ "dist/**/*",
32
+ "types/**/*",
33
+ "internal/package.json",
34
+ "internal/analyzer/package.json",
35
+ "shared/package.json"
36
+ ],
37
+ "dependencies": {
38
+ "@galacean/engine-core": "2.0.0-alpha.54",
39
+ "@galacean/engine-design": "2.0.0-alpha.54",
40
+ "@galacean/engine-math": "2.0.0-alpha.54"
41
+ },
42
+ "scripts": {
43
+ "b:types": "tsc"
44
+ }
6
45
  }
@@ -0,0 +1,5 @@
1
+ {
2
+ "main": "../dist/main.shared.js",
3
+ "module": "../dist/module.shared.js",
4
+ "types": "../types/shared.d.ts"
5
+ }
@@ -0,0 +1,31 @@
1
+ import { ShaderPosition } from "./common/ShaderPosition";
2
+ import { ShaderRange } from "./common/ShaderRange";
3
+ /** Error reported while parsing or analyzing shader source. */
4
+ export declare class GSError extends Error {
5
+ readonly location: ShaderRange | ShaderPosition;
6
+ readonly source: string | undefined;
7
+ readonly file?: string;
8
+ readonly code?: string;
9
+ /**
10
+ * Creates a shader error.
11
+ * @param name - Error category.
12
+ * @param message - Error message.
13
+ * @param location - Source location of the error.
14
+ * @param source - Source text containing the error.
15
+ * @param file - Optional source file name.
16
+ * @param code - Optional diagnostic code.
17
+ */
18
+ constructor(name: GSErrorName, message: string, location: ShaderRange | ShaderPosition, source: string | undefined, file?: string, code?: string);
19
+ /**
20
+ * Formats the error with source context when the authoring parser is available.
21
+ * @returns Human-readable error text.
22
+ */
23
+ toString(): string;
24
+ }
25
+ /** Category assigned to a {@link GSError}. */
26
+ export declare enum GSErrorName {
27
+ PreprocessorError = "PreprocessorError",
28
+ CompilationError = "CompilationError",
29
+ ScannerError = "ScannerError",
30
+ CompilationWarn = "CompilationWarning"
31
+ }
@@ -0,0 +1,11 @@
1
+ declare const parsedShaderPassBrand: unique symbol;
2
+ /**
3
+ * Opaque, immutable handle for a parsed ShaderLab pass.
4
+ *
5
+ * Passes returned by `ShaderAnalyzer.analyze()` can be supplied to `ShaderCompiler.generate()`
6
+ * without parsing the source again or exposing parser internals.
7
+ */
8
+ export interface ParsedShaderPass {
9
+ readonly [parsedShaderPassBrand]: never;
10
+ }
11
+ export {};
@@ -0,0 +1,51 @@
1
+ import { BaseToken } from "./common/BaseToken";
2
+ import { ShaderPosition } from "./common/ShaderPosition";
3
+ import { ShaderRange } from "./common/ShaderRange";
4
+ /**
5
+ * Reuses parser-owned objects while a synchronous compiler consumes one pass at a time.
6
+ *
7
+ * Parsed passes created without this pool remain independently retainable. A caller using the pool
8
+ * must finish consuming a pass before resetting the pool for another parse.
9
+ * @internal
10
+ */
11
+ export declare class ParserObjectPool {
12
+ private readonly _tokens;
13
+ private readonly _positions;
14
+ private readonly _ranges;
15
+ private readonly _nodes;
16
+ /**
17
+ * Resets allocation cursors without releasing the high-water storage.
18
+ * @internal
19
+ */
20
+ reset(): void;
21
+ /**
22
+ * Acquires a reusable token.
23
+ * @returns Token storage owned by this pool.
24
+ * @internal
25
+ */
26
+ createToken(): BaseToken;
27
+ /**
28
+ * Acquires and initializes a reusable source position.
29
+ * @param index - Zero-based source offset.
30
+ * @param line - Zero-based source line.
31
+ * @param column - Zero-based source column.
32
+ * @returns Source-position storage owned by this pool.
33
+ * @internal
34
+ */
35
+ createPosition(index: number, line: number, column: number): ShaderPosition;
36
+ /**
37
+ * Acquires and initializes a reusable source range.
38
+ * @param start - Inclusive range start.
39
+ * @param end - Exclusive range end.
40
+ * @returns Source-range storage owned by this pool.
41
+ * @internal
42
+ */
43
+ createRange(start: ShaderPosition, end: ShaderPosition): ShaderRange;
44
+ /**
45
+ * Acquires a reusable AST node of the requested concrete type.
46
+ * @param type - Concrete AST-node constructor.
47
+ * @returns Node storage owned by this pool.
48
+ * @internal
49
+ */
50
+ createNode<T>(type: new () => T): T;
51
+ }
@@ -0,0 +1,91 @@
1
+ import { GalaceanDataType } from "./common";
2
+ import { BaseToken as Token } from "./common/BaseToken";
3
+ import { ASTNode, TreeNode } from "./parser/AST";
4
+ import { GrammarSymbol, NoneTerminal } from "./parser/GrammarSymbol";
5
+ import { Keyword } from "./common/enums/Keyword";
6
+ export declare class ParserUtils {
7
+ private static _swizzleSets;
8
+ static unwrapNodeByType<T = TreeNode>(node: TreeNode, type: NoneTerminal): T | undefined;
9
+ /**
10
+ * Parse a function-macro parameter-list lexeme (`"(a, b, c)"`) into its parameter
11
+ * names. An empty list `"()"` yields `[]`. Leading/trailing whitespace around each
12
+ * name is trimmed. Empty entries from consecutive commas are filtered out.
13
+ */
14
+ static parseMacroParamList(lexeme: string): string[];
15
+ /**
16
+ * Walk single-child precedence-chain wrappers down to a `VariableIdentifier`,
17
+ * returning the leaf node (or `undefined` for any compound expression).
18
+ *
19
+ * `allowParens` chooses between two callers' needs:
20
+ * - `true` — descend through `( expression )` form, so `(v)` resolves to
21
+ * `v`. Use when the caller substitutes at the expression root
22
+ * (aliasing, renaming); user-written parens carry no extra meaning.
23
+ * - `false` — any 3-child `PrimaryExpression` aborts; `(v)` stays
24
+ * compound. Use when the caller treats the unwrapped node as a single
25
+ * token (IO-struct arg drop, alias detection); user-written parens
26
+ * must not collapse.
27
+ */
28
+ static unwrapBareIdentifier(node: TreeNode, options: {
29
+ allowParens: boolean;
30
+ }): ASTNode.VariableIdentifier | undefined;
31
+ /**
32
+ * Lexeme variant of `unwrapBareIdentifier({ allowParens: true })` for callers
33
+ * that already work with strings. Returns `null` for compound expressions.
34
+ */
35
+ static extractDirectIdentLexeme(expr: TreeNode): string | null;
36
+ /**
37
+ * Finds the final syntactic statement inside the parser's block/statement wrappers.
38
+ * @param node - Block, statement list, wrapper, or leaf node.
39
+ * @returns Final statement leaf, or `undefined` for an empty block.
40
+ * @internal
41
+ */
42
+ static lastStatement(node: TreeNode): TreeNode | undefined;
43
+ /**
44
+ * Validate a `.field` access on a vector as a GLSL swizzle. Returns an error message when the
45
+ * access is an invalid swizzle on a known vector type, or `null` when it is valid or the base
46
+ * is not a known vector (struct member / scalar / unresolved — left for other checks).
47
+ * @param baseType - Resolved receiver type.
48
+ * @param swizzle - Selected component names.
49
+ * @param size - Proven component count when a nested swizzle has no resolved expression type.
50
+ * @returns A reason for invalid selection, or `null` for valid or unresolved receivers.
51
+ */
52
+ static swizzleError(baseType: GalaceanDataType | undefined, swizzle: string, size?: number): string | null;
53
+ /**
54
+ * Evaluate an expression node to its compile-time numeric literal, unwrapping the single-child
55
+ * precedence chain and parenthesised groups. Returns `undefined` for anything that is not a plain
56
+ * numeric literal (identifiers, compound/arithmetic expressions) — callers treat that as "not a
57
+ * known constant" and skip (continue-with-unknown), so this never produces a false positive.
58
+ */
59
+ static constNumericValue(node: TreeNode): number | undefined;
60
+ /**
61
+ * Evaluates a constant integral expression when its exact value is known from the parsed AST.
62
+ * Macro-backed or otherwise variant-dependent expressions return `undefined` so callers can
63
+ * preserve them for the runtime preprocessor.
64
+ * @param node - Integral expression to evaluate.
65
+ * @returns The exact 32-bit value, or `undefined` when it cannot be proven statically.
66
+ * @internal
67
+ */
68
+ static constIntegerValue(node: TreeNode): number | undefined;
69
+ private static _constIntegerValue;
70
+ private static _constInitializer;
71
+ private static _operatorLexeme;
72
+ private static _normalizeInteger;
73
+ /** Recursively walk a `type_qualifier` token chain for a keyword (e.g. `const`, `flat`; test by value as CONST === 0). */
74
+ static hasQualifier(node: TreeNode, keyword: Keyword): boolean;
75
+ /**
76
+ * Whether an expression is a compile-time constant per GLSL ES §4.3.3. Covers numeric literals,
77
+ * bare identifiers whose symbol is `const`, `#define`d names, built-in function calls whose
78
+ * arguments are themselves constant (e.g. `sin(0.5)`, `vec3(1.0, 2.0, 3.0)`), and any compound
79
+ * expression (binary / unary / ternary) whose sub-expressions are all constant.
80
+ * Non-constant references (uniforms, non-const locals) return false. Called only by diagnostics
81
+ * (NonConstInitializer / NonConstArraySize) — codegen doesn't consult it.
82
+ * @param node - Expression to classify using its retained symbol-resolution facts.
83
+ * @returns Whether every reachable operand is a compile-time constant.
84
+ */
85
+ static isConstExpr(node: TreeNode): boolean;
86
+ private static _isBooleanLiteral;
87
+ /** The first arithmetic-binary operand whose type can't be an operand (bool/sampler/struct), else undefined. */
88
+ static firstNonArithmeticOperand(a: TreeNode | Token, b: TreeNode | Token): ASTNode.ExpressionAstNode | undefined;
89
+ static toString(sm: GrammarSymbol): string;
90
+ static isTerminal(sm: GrammarSymbol): boolean;
91
+ }
@@ -0,0 +1,71 @@
1
+ import type { PreprocessorConditionalArm } from "./preprocessor/PreprocessorCondition";
2
+ import type { ASTNode } from "./parser/AST";
3
+ import type { BranchSignature } from "./common/BaseToken";
4
+ import { GSError } from "./GSError";
5
+ import type { ShaderSourceMapSegment, ShaderSourceScope } from "./ir";
6
+ export type IncludeMap = {
7
+ readonly [includeName: string]: string | undefined;
8
+ };
9
+ export interface PreprocessResult {
10
+ /** Expanded shader source. */
11
+ content: string;
12
+ /** Include-resolution failures collected while expanding the source. */
13
+ errors: GSError[];
14
+ /** Mapping from expanded offsets back to the source chunks that produced them. */
15
+ sourceMap: ShaderSourceMapSegment[];
16
+ /** Compact semantic inheritance ranges, independent of diagnostic source mapping. */
17
+ sourceScopes: ShaderSourceScope[];
18
+ /** Source-owned arm facts, keyed by the generated offset of its directive's `#`. */
19
+ conditionalArms: ReadonlyMap<number, PreprocessorConditionalArm>;
20
+ }
21
+ export type ChunkOutputCache = Map<string, PreprocessResult>;
22
+ export interface MacroDefineInfo {
23
+ isFunction: boolean;
24
+ params: string[];
25
+ /** Value AST. Set when the replacement list parses as `expression` (which
26
+ * includes comma-separated lists per C99 §6.10.3); absent for the GLSL ES
27
+ * 3.00 §3.4 opaque cases the grammar can't reduce (empty, type-alias keyword,
28
+ * trailing punctuation, unbalanced bracket, trailing operator). Identifier
29
+ * references inside are collected by `MacroCallSymbol._collectIdentifierRefs`
30
+ * walking this subtree. */
31
+ valueAst?: ASTNode.Expression;
32
+ /** Whitespace-normalized directive text. Dedup key against re-includes in
33
+ * the same branch; differing values produce different keys. */
34
+ dedupKey: string;
35
+ /** `#ifdef` branch at registration time; call sites filter to visible entries. */
36
+ branch: BranchSignature;
37
+ }
38
+ export interface MacroDefineList {
39
+ [macroName: string]: MacroDefineInfo[];
40
+ }
41
+ export declare class Preprocessor {
42
+ private static readonly _includePathReg;
43
+ private static readonly _directiveReg;
44
+ static parse(source: string, basePathForIncludeKey: string, includeMap: IncludeMap, chunkOutputCache: ChunkOutputCache, sourceFile?: string, sourceScopeStarts?: readonly number[]): string;
45
+ /**
46
+ * Expands includes and returns any include-resolution failures with source locations.
47
+ *
48
+ * @param source - Source to preprocess.
49
+ * @param basePathForIncludeKey - Base URL for relative include paths.
50
+ * @param includeMap - Include-path lookup table.
51
+ * @param chunkOutputCache - Cache for expanded include chunks.
52
+ * @param sourceFile - Canonical path of the root source.
53
+ * @param trackSourceMap - Whether to retain generated-to-original source segments.
54
+ * @param sourceScopeStarts - Start offsets of inherited ShaderLab content layers.
55
+ * @returns The expanded source and collected errors.
56
+ */
57
+ static parseWithErrors(source: string, basePathForIncludeKey: string, includeMap: IncludeMap, chunkOutputCache: ChunkOutputCache, sourceFile?: string, trackSourceMap?: boolean, sourceScopeStarts?: readonly number[]): PreprocessResult;
58
+ private static _expand;
59
+ /** Restores physical provenance after preprocessing the logically spliced source. */
60
+ private static _restoreSplicedSource;
61
+ private static _physicalOffset;
62
+ private static _sourceScopeAt;
63
+ private static _nextSourceScopeStart;
64
+ private static _maskDirectiveTrivia;
65
+ private static _stripLineComment;
66
+ private static _maskText;
67
+ private static _resolveIncludePath;
68
+ private static _canonicalIncludeURL;
69
+ private static _createPreprocessorError;
70
+ private static _positionAt;
71
+ }
@@ -0,0 +1 @@
1
+ export { parsePreprocessorExpression } from "@galacean/engine-design";
@@ -0,0 +1,9 @@
1
+ import { GSErrorName } from "./GSError";
2
+ import { ShaderRange } from "./common/ShaderRange";
3
+ import { ShaderPosition } from "./common/ShaderPosition";
4
+ import { GSError } from "./GSError";
5
+ export declare class ShaderCompilerUtils {
6
+ static createPosition(index: number, line?: number, column?: number): ShaderPosition;
7
+ static createRange(start: ShaderPosition, end: ShaderPosition): ShaderRange;
8
+ static createGSError(message: string, errorName: GSErrorName, source: string | undefined, location: ShaderRange | ShaderPosition, code?: string, file?: string): GSError;
9
+ }
@@ -0,0 +1,39 @@
1
+ import type { StructProp } from "../parser/types";
2
+ import type { ShaderRange } from "../common/ShaderRange";
3
+ import type { ShaderClueIR } from "../ir/ShaderClueIR";
4
+ import { ShaderCoreInfo } from "../ir/ShaderCoreInfo";
5
+ /**
6
+ * A definite MRT member contract violation shared by analyzer and compiler.
7
+ * @internal
8
+ */
9
+ export interface ShaderMrtOutputIssue {
10
+ /** Offending MRT member. */
11
+ readonly prop: StructProp;
12
+ /** GLES lowering reason the member cannot be lowered consistently. */
13
+ readonly kind: "missing-location" | "invalid-location" | "duplicate-location" | "invalid-type";
14
+ }
15
+ /**
16
+ * A member owner resolution that a backend cannot lower uniformly.
17
+ * @internal
18
+ */
19
+ export interface ShaderStructMemberOwnerIssue {
20
+ /** Call-site range of the unsafe member projection. */
21
+ readonly location: ShaderRange;
22
+ /** GLES lowering reason the member projection is unsafe. */
23
+ readonly kind: "mixed-owner-roles" | "runtime-expanded-io-owner" | "unresolved-owner" | "incompatible-io-member";
24
+ /** Whether branch analysis proves the conflict or cannot decide it. */
25
+ readonly certainty: "definite" | "unknown";
26
+ }
27
+ /**
28
+ * GLES flattening constraints derived from neutral entry and IO facts. These checks belong to
29
+ * the target contract: another backend may preserve struct values or support other output types.
30
+ * The analyzer shares this policy without loading a compiler or creating a graphics context.
31
+ * @internal
32
+ */
33
+ export declare class GLESShaderInfo {
34
+ readonly mrtOutputIssues: readonly ShaderMrtOutputIssue[];
35
+ readonly invalidMrtReturnLocations: readonly ShaderRange[];
36
+ readonly invalidVaryingReturnLocations: readonly ShaderRange[];
37
+ readonly structMemberOwnerIssues: readonly ShaderStructMemberOwnerIssue[];
38
+ constructor(ir: ShaderClueIR, coreInfo: ShaderCoreInfo);
39
+ }
@@ -0,0 +1,61 @@
1
+ import { ShaderPosition, ShaderRange } from ".";
2
+ import { BaseToken } from "./BaseToken";
3
+ import type { ParserObjectPool } from "../ParserObjectPool";
4
+ export type OnToken = (token: BaseToken, scanner: BaseLexer) => void;
5
+ /**
6
+ * @internal
7
+ */
8
+ export declare abstract class BaseLexer {
9
+ protected readonly _objectPool?: ParserObjectPool;
10
+ static isDigit(charCode: number): boolean;
11
+ static isHexDigit(charCode: number): boolean;
12
+ static isAlpha(charCode: number): boolean;
13
+ static isAlnum(charCode: number): boolean;
14
+ static isPreprocessorStartChar(charCode: number): boolean;
15
+ /**
16
+ * If `i` points at the start of a `/* … *\/` block comment, return the index
17
+ * just past the closing `*\/`. Otherwise return `i` unchanged. If the
18
+ * comment is unterminated, returns `len` (clamped, never overshoots).
19
+ * Single source of truth for block-comment scanning across the lexer.
20
+ */
21
+ protected static _skipBlockComment(src: string, i: number, len: number): number;
22
+ /**
23
+ * If `i` points at the start of a `//` line comment, return the index of the
24
+ * terminating newline (or `len` at EOF). The newline itself is NOT consumed
25
+ * — callers decide whether `\n` is whitespace or a logical separator.
26
+ * Otherwise return `i` unchanged.
27
+ */
28
+ protected static _skipLineComment(src: string, i: number, len: number): number;
29
+ static isWhiteSpaceChar(charCode: number, includeBreak: boolean): boolean;
30
+ protected _currentIndex: number;
31
+ protected _source: string;
32
+ protected _column: number;
33
+ protected _line: number;
34
+ get currentIndex(): number;
35
+ get source(): string;
36
+ get line(): number;
37
+ get column(): number;
38
+ constructor(source?: string, _objectPool?: ParserObjectPool);
39
+ setSource(source: string): void;
40
+ getShaderPosition(backOffset?: number): ShaderPosition;
41
+ /** @internal */
42
+ protected _createPosition(index: number, line: number, column: number): ShaderPosition;
43
+ /** @internal */
44
+ protected _createToken(): BaseToken;
45
+ /** @internal */
46
+ protected _createEOFToken(): BaseToken;
47
+ /** @internal */
48
+ protected _createRange(start: ShaderPosition, end: ShaderPosition): ShaderRange;
49
+ isEnd(): boolean;
50
+ getCurChar(): string;
51
+ getCurCharCode(): number;
52
+ advance(count: number): void;
53
+ skipSpace(includeLineBreak: boolean): void;
54
+ skipCommentsAndSpace(): void;
55
+ peek(to: number): string;
56
+ scanLexeme(lexeme: string): void;
57
+ scanTwoExpectedLexemes(lexeme1: string, lexeme2: string): string | null;
58
+ throwError(pos: ShaderPosition | ShaderRange, ...msgs: unknown[]): void;
59
+ scanPairedChar(left: string, right: string, balanced: boolean, skipLeading: boolean): string;
60
+ abstract scanToken(onToken?: OnToken): void;
61
+ }
@@ -0,0 +1,105 @@
1
+ import { ShaderRange, ShaderPosition } from ".";
2
+ import type { ParserObjectPool } from "../ParserObjectPool";
3
+ import type { PreprocessorConditionalArm } from "../preprocessor/PreprocessorCondition";
4
+ /**
5
+ * One condition in a branch signature: `defined: true` for `#ifdef X` (the
6
+ * branch is active when `X` is defined), `defined: false` for `#ifndef X` /
7
+ * after `#else` (active when `X` is undefined).
8
+ */
9
+ export interface BranchConstraint {
10
+ name: string;
11
+ defined: boolean;
12
+ /** Shared source-preprocessor authority for truth and inherited declaration replacement. */
13
+ sourceArm?: PreprocessorConditionalArm;
14
+ /** Lexical conditional-chain identity. All `#if/#elif/#else` arms in one chain share it. */
15
+ conditionalGroup?: number;
16
+ /** Lexical arm within `conditionalGroup`; different arms cannot execute together. */
17
+ conditionalArm?: number;
18
+ /** Whether this conditional chain covers every configuration. */
19
+ conditionalComplete?: boolean;
20
+ /** Number of arms in this complete conditional chain. */
21
+ conditionalArmCount?: number;
22
+ /** Reachability of each arm in this complete conditional chain. */
23
+ conditionalReachableArms?: readonly boolean[];
24
+ /** A recognized `#if` condition; unsupported expressions stay undefined. */
25
+ condition?: BranchCondition;
26
+ /** Conditions of earlier arms that must be false for this `#elif`/`#else` arm to run. */
27
+ precedingConditions?: readonly BranchCondition[];
28
+ /**
29
+ * Shared `#undef` events for this guard macro. Each guard records the event index at its entry
30
+ * (and again when it defines itself) so conflict checks only consider invalidations between two
31
+ * guard occurrences.
32
+ * @internal
33
+ */
34
+ guardUndefBranches?: readonly BranchSignature[];
35
+ /** @internal */
36
+ guardUndefStart?: number;
37
+ /** Whether this arm has directly defined its own guard macro before the current source position. */
38
+ selfGuarding?: boolean;
39
+ }
40
+ /** A single-macro condition that can be compared without evaluating a macro configuration. */
41
+ export type BranchCondition = {
42
+ kind: "constant";
43
+ value: boolean;
44
+ } | {
45
+ kind: "defined";
46
+ name: string;
47
+ defined: boolean;
48
+ version: number;
49
+ } | {
50
+ kind: "comparison";
51
+ name: string;
52
+ operator: "==" | "!=" | ">" | ">=" | "<" | "<=";
53
+ value: number;
54
+ version: number;
55
+ } | {
56
+ /** Canonicalized conjunction/disjunction of simple macro conditions. */
57
+ kind: "expression";
58
+ expression: string;
59
+ operator: "&&" | "||";
60
+ operands: readonly BranchCondition[];
61
+ names: readonly string[];
62
+ versions: readonly number[];
63
+ negated: boolean;
64
+ /** Whether the expression preserves a canonical comparison that this layer must not evaluate. */
65
+ opaque?: boolean;
66
+ };
67
+ /**
68
+ * Snapshot of the `#ifdef`/`#ifndef`/`#else` stack at a source position. An
69
+ * empty signature means unconditional (top-level). Constraints are conjunctive:
70
+ * the position is active iff every constraint holds. Produced by the Lexer
71
+ * (the sole branch-stack maintainer) and stamped onto every emitted token +
72
+ * every registered `MacroDefineInfo`.
73
+ */
74
+ export type BranchSignature = readonly BranchConstraint[];
75
+ /** Result of checking whether macro-guarded declarations cover a reference site. */
76
+ export type BranchCoverage = "covered" | "uncovered" | "unknown";
77
+ /** Whether at least one macro configuration is proven to reach a branch. */
78
+ export type BranchReachability = "reachable" | "unreachable" | "unknown";
79
+ /** Whether two declarations are proven to coexist, proven exclusive, or unresolved. */
80
+ export type DeclarationCoexistence = "coexist" | "exclusive" | "unknown";
81
+ export declare const EMPTY_BRANCH: BranchSignature;
82
+ export { sameBranch } from "./BranchIdentity";
83
+ /**
84
+ * Token retained by parser AST and parsed-pass results.
85
+ *
86
+ * Instances are pass-owned because their ranges and lexemes can outlive the parse call. A reusable
87
+ * allocator must therefore be scoped to the lifetime of the whole parsed pass, not globally cleared.
88
+ */
89
+ export declare class BaseToken<T extends number = number> {
90
+ private readonly _objectPool?;
91
+ type: T;
92
+ lexeme: string;
93
+ location: ShaderRange;
94
+ /** Branch signature snapshot at the point this token was emitted. Empty
95
+ * signature (default) means top-level / unconditional. The Lexer tags
96
+ * every token; downstream code (AST nodes built from tokens) can read
97
+ * the field directly to know which `#ifdef` branch they're inside. */
98
+ branch: BranchSignature;
99
+ inMacroDefinition: boolean;
100
+ /** @internal */
101
+ constructor(_objectPool?: ParserObjectPool);
102
+ set(type: T, lexeme: string, start: ShaderPosition): any;
103
+ set(type: T, lexeme: string, location: ShaderRange): any;
104
+ }
105
+ export declare const EOF: BaseToken<number>;
@@ -0,0 +1,84 @@
1
+ import type { BranchSemantics } from "./BranchSemantics";
2
+ import type { BranchCondition, BranchConstraint, BranchCoverage, BranchReachability, BranchSignature, DeclarationCoexistence } from "./BaseToken";
3
+ /**
4
+ * Whether two simple macro conditions are exact logical negations.
5
+ * @param left - First simple condition.
6
+ * @param right - Second simple condition.
7
+ * @returns Whether exactly one condition holds for every macro value.
8
+ */
9
+ export declare function areConditionsComplementary(left?: BranchCondition, right?: BranchCondition): boolean;
10
+ /**
11
+ * Whether a `#if`/`#elif` chain contains an arm that covers every remaining macro configuration.
12
+ * @param constraints - Conditions in source order within one lexical conditional chain.
13
+ * @returns Whether no implicit fall-through configuration remains.
14
+ * @internal
15
+ */
16
+ export declare function isConditionalChainExhaustive(constraints: readonly BranchConstraint[]): boolean;
17
+ /**
18
+ * `defBranch` is visible from `callSiteBranch` when every macro configuration that reaches the
19
+ * reference also reaches the declaration. Compatibility alone is not enough: a declaration in
20
+ * `#ifdef A` is not visible from an unconditional reference, because `A` can be absent there.
21
+ * Extracted from Lexer so common/SymbolTable can consume it without pulling the whole lexer in as
22
+ * a dependency.
23
+ * @param defBranch - Declaration-side branch signature.
24
+ * @param callSiteBranch - Reference-side branch signature.
25
+ * @returns Whether the declaration is visible from the reference branch.
26
+ */
27
+ export declare function isBranchVisibleFrom(defBranch: BranchSignature, callSiteBranch: BranchSignature): boolean;
28
+ /**
29
+ * Whether a later declaration can coexist with an earlier declaration in one preprocessed shader.
30
+ * Besides ordinary mutually-exclusive conditional arms, an earlier self-defining `#ifndef` arm
31
+ * suppresses later `#ifndef` arms for that macro unless a compatible intervening `#undef` reopened
32
+ * the guard. Argument order therefore follows source/insertion order.
33
+ * @param earlier - Branch signature of an existing declaration.
34
+ * @param later - Branch signature of the declaration currently being inserted.
35
+ * @returns Whether both declarations can be emitted by one macro configuration.
36
+ */
37
+ export declare function canDeclarationsCoexist(earlier: BranchSignature, later: BranchSignature): boolean;
38
+ /**
39
+ * Classify whether two declarations can be emitted by one macro configuration.
40
+ * @param earlier - Branch signature of an existing declaration.
41
+ * @param later - Branch signature of the declaration currently being inserted.
42
+ * @returns Proven coexistence, proven exclusivity, or an unresolved complex condition.
43
+ */
44
+ export declare function getDeclarationCoexistence(earlier: BranchSignature, later: BranchSignature): DeclarationCoexistence;
45
+ /**
46
+ * Determines whether a lexical branch can be emitted by at least one macro configuration.
47
+ * @param branch - Branch constraints to test.
48
+ * @returns Whether the constraints are satisfiable.
49
+ */
50
+ export declare function isBranchReachable(branch: BranchSignature): boolean;
51
+ /**
52
+ * Classifies branch reachability without treating an incomplete proof as reachable evidence.
53
+ * @param branch - Branch constraints to classify.
54
+ * @returns Proven reachability, proven impossibility, or an unresolved complex condition.
55
+ */
56
+ export declare function getBranchReachability(branch: BranchSignature): BranchReachability;
57
+ /**
58
+ * Determines whether two lexical branches can be emitted by one macro configuration.
59
+ * @param left - First branch signature.
60
+ * @param right - Second branch signature.
61
+ * @returns Whether the combined constraints are satisfiable.
62
+ */
63
+ export declare function canBranchesOverlap(left: BranchSignature, right: BranchSignature): boolean;
64
+ /**
65
+ * Whether declarations from a complete set of conditional arms cover every configuration that can
66
+ * reach `callSiteBranch`. A single declaration must be guaranteed by the call site; alternatively,
67
+ * one declaration in every arm of an exhaustive conditional chain is sufficient.
68
+ * @param candidates - Branch signatures of matching declarations in one lexical scope.
69
+ * @param callSiteBranch - Branch signature at the reference.
70
+ * @returns Whether the reference is backed by a declaration on every reachable macro path.
71
+ */
72
+ export declare function canBranchesCoverCallsite(candidates: readonly BranchSignature[], callSiteBranch: BranchSignature): boolean;
73
+ /**
74
+ * Classify declaration coverage without treating an incomplete symbolic proof as a definite error.
75
+ *
76
+ * `uncovered` is returned only when a concrete counterexample follows from atomic macro facts.
77
+ * Complex or opaque expressions stay `unknown`; incomplete proof is not a diagnostic fact.
78
+ * @param candidates - Branch signatures of matching declarations in one lexical scope.
79
+ * @param callSiteBranch - Branch signature at the reference.
80
+ * @returns Whether coverage is proven, disproven, or unknown.
81
+ */
82
+ export declare function getBranchCoverage(candidates: readonly BranchSignature[], callSiteBranch: BranchSignature): BranchCoverage;
83
+ /** Analyzer branch-proof implementation injected into analyzer parser instances. @internal */
84
+ export declare const branchAnalysis: BranchSemantics;