001package Torello.Browser.JsonAST;
002
003import static Torello.Java.C.*;
004
005import Torello.Java.Additional.Ret2;
006
007import Torello.Java.EXCC;
008import Torello.Java.FileRW;
009import Torello.Java.StrPrint;
010import Torello.Java.StorageWriter;
011
012import java.io.IOException;
013import java.io.File;
014
015/**
016 * <B>AST Build Driver</B>.
017 *
018 * <BR /><BR />This top-level builder orchestrates the end-to-end pipeline for transforming the
019 * Chrome DevTools Protocol (CDP) schema JSON files into the Java-HTML abstract syntax tree (AST)
020 * representation and derived outputs.
021 *
022 * <BR /><BR />The build process follows a <I>compiler-style</I> sequence of phases:
023 * 
024 * <BR /><BR /><UL CLASS=JDUL>
025 * <LI> <B>Constructors:</B> Parse raw JSON into untyped AST node tuples with no side effects.</LI>
026 * 
027 * <LI> <B>LinkTypes:</B> Wire parents, resolve <CODE>ref4</CODE> references, and set cross-links.
028 *      </LI>
029 * 
030 * <LI> <B>SimplifyTypes:</B> Normalize and simplify types (collapse aliases, lift unions, etc.).
031 *      </LI>
032 * 
033 * <LI> <B>ToHTML:</B> Emit human-readable documentation pages for both
034 *     <CODE>browser_protocol.json</CODE> and <CODE>js_protocol.json</CODE>.
035 *     </LI>
036 * 
037 * <LI><B>ToString:</B> Provide summaries suitable for debugging, logs, and diffs.</LI>
038 * </UL>
039 *
040 * <BR />All semantic violations are reported via {@link javax.json.JsonException} with contextual
041 * notes. This avoids unchecked {@link ClassCastException} and ensures validation through explicit
042 * {@link javax.json.JsonValue.ValueType} gates.
043 *
044 * <BR /><BR />This class is intended for use by build tools and advanced users who need to
045 * regenerate the API documentation or validate schema changes. It is not part of the runtime API.
046 */
047@Torello.JavaDoc.Annotations.StaticFunctional
048@Torello.JavaDoc.Annotations.JDHeaderBackgroundImg(EmbedTagFileID="SERIALIZER_JDHBI")
049public class AST_BUILD
050{
051    private AST_BUILD() { }
052
053    private static final String FS = File.separator;
054
055    /**
056     * Command line variant of the generate method which uses the Java-HTML Default File &amp;
057     * Directory Names.
058     */
059    public static void main(String[] args) throws IOException
060    {
061        generate(
062            "Torello" + FS + "Browser" + FS + "doc-files" + FS + "protocol_as_html" + FS,
063            "Torello" + FS + "Browser" + FS + "JsonAST" + FS + "data-files" + FS,
064            "Torello" + FS + "Browser" + FS + "doc-files" + FS + "protocol_as_json" + FS
065        );
066    }
067
068    /**
069     * Executes the full JSONā†’AST build pipeline for the Chrome DevTools Protocol schema.
070     *
071     * <BR /><BR />This method reads the canonical CDP specification files
072     * (<CODE>browser_protocol.json</CODE> and <CODE>js_protocol.json</CODE>) from the given
073     * <CODE>dataFileDir</CODE>, parses them into {@link API} instances, runs the linker and
074     * simplification phases, and finally writes the generated HTML documentation into the provided
075     * <CODE>htmlFileOutputDir</CODE>.
076     * 
077     * @param htmlFileOutputDir Directory where the generated HTML protocol documentation
078     * will be written.
079     * 
080     * @param dataFileOutputDir Target location for writing two '.dat' files
081     * 
082     * @param jsonFileSourceDir Directory containing the JSON schema input files:
083     * <B><CODE><A HREF='../doc-files/protocol_as_json/browser_protocol.json'>
084     * browser_protocol.json</A></CODE></B> and
085     * <B><CODE><A HREF='../doc-files/protocol_as_json/js_protocol.json'>
086     * js_protocol.json</A></CODE></B>.
087     *
088     * @throws IOException if the schema files cannot be read or the HTML output cannot be written.
089     */
090    public static void generate(
091            final String htmlFileOutputDir,
092            final String dataFileOutputDir,
093            final String jsonFileSourceDir
094        )
095        throws IOException
096    {
097        final StorageWriter sw = new StorageWriter();
098
099
100        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
101        printPhaseToTerminal(sw, "Parsign Raw JSON Files ");
102        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
103
104        final String    browserAPI_Filename = jsonFileSourceDir + "browser_protocol.json";
105        final String    jsAPI_Filename      = jsonFileSourceDir + "js_protocol.json";
106        final API       browser             = new API(sw, browserAPI_Filename, "BrowserAPI");
107        final API       js                  = new API(sw, jsAPI_Filename, "JavaScriptAPI");
108
109
110        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
111        printPhaseToTerminal(sw, "Running the Linker");
112        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
113
114        Linker.run(sw, browser, js);
115
116
117        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
118        printPhaseToTerminal(sw, "Writing Data Files");
119        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
120        // 
121        // return new Ret2<>(browserData, jsData);  
122        // Don't confuse which one is which.  Save these to explicitly named variables
123
124        final Ret2<InfoData, InfoData>  extraData   = ExtraData.run(sw, browser, js);
125        final InfoData                  browserData = extraData.a;
126        final InfoData                  jsData      = extraData.b;
127
128        // Container Data-Class "SERIALIZED_AST" just keeps these four types together
129        final String            fName   = dataFileOutputDir + SERIALIZED_AST.FILE_NAME_JAR;
130        final SERIALIZED_AST    dat     = new SERIALIZED_AST(browser, js, browserData, jsData);
131
132        try 
133        {
134            sw.println("Writing File: " + BYELLOW + fName + RESET);
135            FileRW.writeObjectToFileNOCNFE(dat, fName, true);
136        }
137
138        catch (IOException ioe)
139        {
140            sw.println(EXCC.toString(ioe) + "\nExiting...");
141            System.exit(0);
142        }
143
144
145        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
146        printPhaseToTerminal(sw, "Writing HTML Files");
147        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
148
149        WriteBothHTMLFiles.write(htmlFileOutputDir, browser, js);
150        sw.println();
151    }
152
153    static void printPhaseToTerminal(final StorageWriter sw, final String phaseName)
154    {
155        sw.println(
156            "\n\n" +
157            BBLUE +
158            "*****************************************************************************\n" +
159            RESET +
160            " " + BRED_BKGND + ' ' + phaseName + ' '  + RESET + "\n" +
161            BBLUE +
162            "*****************************************************************************\n" +
163            RESET
164        );
165    }
166}