package gudusoft.gsqlparser.catalog.input.readers;

import gudusoft.gsqlparser.EDbVendor;
import gudusoft.gsqlparser.catalog.input.CatalogInputException;
import gudusoft.gsqlparser.catalog.input.CatalogInputKind;
import gudusoft.gsqlparser.catalog.input.CatalogInputReader;
import gudusoft.gsqlparser.catalog.input.CatalogInputReaderFactory;
import gudusoft.gsqlparser.catalog.input.CatalogInputSource;
import gudusoft.gsqlparser.catalog.input.CatalogLoadOptions;
import gudusoft.gsqlparser.catalog.input.model.CatalogModel;
import gudusoft.gsqlparser.catalog.input.model.CatalogSourceInfo;
import gudusoft.gsqlparser.catalog.input.model.ColumnModel;
import gudusoft.gsqlparser.catalog.input.model.ConstraintModel;
import gudusoft.gsqlparser.catalog.input.model.DefaultsConfig;
import gudusoft.gsqlparser.catalog.input.model.IdentifierConfig;
import gudusoft.gsqlparser.catalog.input.model.IndexModel;
import gudusoft.gsqlparser.catalog.input.model.PolicyTagModel;
import gudusoft.gsqlparser.catalog.input.model.RoutineModel;
import gudusoft.gsqlparser.catalog.input.model.SchemaModel;
import gudusoft.gsqlparser.catalog.input.model.SequenceModel;
import gudusoft.gsqlparser.catalog.input.model.SynonymModel;
import gudusoft.gsqlparser.catalog.input.model.TableModel;
import gudusoft.gsqlparser.catalog.input.model.UnifiedCatalogModel;
import gudusoft.gsqlparser.catalog.input.model.ViewModel;
import gudusoft.gsqlparser.catalog.runtime.CatalogObjectKind;
import gudusoft.gsqlparser.sqlenv.IdentifierInputForm;
import gudusoft.gsqlparser.sqlenv.TSQLEnv;
import gudusoft.gsqlparser.util.json.JSON;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.Reader;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.util.Collections;
import java.util.List;
import java.util.Map;

/**
 * Reader for {@link CatalogInputKind#JSON_MANIFEST} sources. Parses a JSON document into
 * {@link UnifiedCatalogModel} via {@link JSON#parseObject(String)} (the in-tree
 * {@code gudusoft.gsqlparser.util.json}, no new compile-scope dependency — see spike
 * {@code docs/designs/catalog-input-interface-spikes/json-dependency.md}).
 *
 * <p>The reader walks the parsed {@code Map}/{@code List} tree manually rather than using
 * reflection-based mapping. Builders apply per-field validation; missing required fields
 * fail with {@link CatalogInputException}; unknown fields are tolerated for forward
 * compatibility with manifests that add new keys.</p>
 *
 * <p>Manifest schema (key fields, top-level keys are case-sensitive):</p>
 * <pre>{@code
 * {
 *   "apiVersion": "1",                    // optional, defaults to "1"
 *   "vendor": "oracle",                   // required; matches EDbVendor name with or
 *                                         // without the "dbv" prefix (case-insensitive)
 *   "source": { "name": "...", "readMillis": 0 },
 *   "identifier": { ...IdentifierConfig fields... },
 *   "defaults": { "catalog": "...", "schema": "...", "server": "..." },
 *   "catalogs": [
 *     { "name": "...", "schemas": [
 *         { "name": "...",
 *           "tables":     [{ "name": "...", "columns": [...], "constraints": [...],
 *                            "indexes": [...], "properties": {} }],
 *           "views":      [{ "name": "...", "definition": "...",
 *                            "materialized": false, "columns": [...] }],
 *           "routines":   [{ "name": "...", "kind": "FUNCTION|PROCEDURE|PACKAGE|ROUTINE",
 *                            "returns": "...", "parameters": [...] }],
 *           "synonyms":   [{ "name": "...", "target": "schema.object" }],
 *           "sequences":  [{ "name": "...", "startsWith": 1, "incrementBy": 1 }]
 *         }
 *     ]}
 *   ]
 * }
 * }</pre>
 */
public final class JsonManifestCatalogInputReader implements CatalogInputReader {

    public JsonManifestCatalogInputReader() {
    }

    @Override
    public CatalogInputKind kind() {
        return CatalogInputKind.JSON_MANIFEST;
    }

    @Override
    public boolean supports(CatalogInputSource source, CatalogLoadOptions options) {
        if (source == null || source.inMemoryModel() != null) {
            return false;
        }
        CatalogInputKind declared = source.declaredKind();
        if (declared == CatalogInputKind.JSON_MANIFEST || declared == CatalogInputKind.JSON) {
            return true;
        }
        // Default-claim by extension when caller didn't declare a kind. Both Path and
        // URL inputs are first-class — for URL we walk the file portion of the URI to
        // ignore a query string or fragment.
        if (declared == null) {
            String n = null;
            if (source.path() != null) {
                n = source.path().toString();
            } else if (source.url() != null) {
                n = source.url().getPath();
            }
            if (n != null) {
                // Only claim plain JSON. JSONC (.jsonc) carries // and /* */ comments
                // that the in-tree gudusoft.gsqlparser.util.json parser does not handle;
                // claiming it here would route to a reader that fails on parse. Phase 2
                // can add a JSONC-stripping reader if needed.
                return endsWithIgnoreAscii(n, ".json");
            }
        }
        return false;
    }

    @Override
    public UnifiedCatalogModel read(CatalogInputSource source, CatalogLoadOptions options)
            throws CatalogInputException {
        if (source == null) {
            throw new CatalogInputException("JsonManifestCatalogInputReader: source is required");
        }
        long start = System.currentTimeMillis();
        String text = readAll(source);
        Object parsed;
        try {
            parsed = JSON.parseObject(text);
        } catch (RuntimeException ex) {
            throw new CatalogInputException(
                "Failed to parse JSON manifest from " + source.name() + ": " + ex.getMessage(),
                ex);
        }
        if (!(parsed instanceof Map)) {
            throw new CatalogInputException(
                "JSON manifest root must be an object (got " + typeOf(parsed) + ")");
        }
        @SuppressWarnings("unchecked")
        Map<Object, Object> root = (Map<Object, Object>) parsed;

        try {
            EDbVendor vendor = parseVendor(asString(root, "vendor", true));
            UnifiedCatalogModel.Builder mb = UnifiedCatalogModel.builder().vendor(vendor);

            String apiVersion = asString(root, "apiVersion", false);
            if (apiVersion != null) mb.apiVersion(apiVersion);

            IdentifierConfig identifier = parseIdentifier(asMap(root, "identifier"), vendor);
            if (identifier != null) mb.identifierConfig(identifier);

            DefaultsConfig defaults = parseDefaults(asMap(root, "defaults"));
            if (defaults != null) mb.defaults(defaults);

            // A manifest is a catalog export, so its names are the stored names unless the
            // file says otherwise. A misspelt value throws: guessing the form silently
            // resolves the wrong objects (design doc, section 6).
            IdentifierInputForm declaredForm = TSQLEnv.parseNameForm(root.get("nameForm"), null);
            if (declaredForm != null) {
                mb.nameForm(declaredForm);
            } else {
                mb.defaultNameForm(IdentifierInputForm.CATALOG_STORED);
            }

            Map<Object, Object> sourceObj = asMap(root, "source");
            CatalogSourceInfo info = parseSourceInfo(sourceObj, source, start);
            mb.sourceInfo(info);

            for (Object cobj : asList(root, "catalogs")) {
                mb.addCatalog(parseCatalog(asMapStrict(cobj, "catalogs[i]")));
            }
            return mb.build();
        } catch (IllegalArgumentException ex) {
            // Model builders enforce structural invariants (non-empty names, vendor
            // consistency, etc.) by throwing IllegalArgumentException. Surface those
            // through the reader's checked-exception channel so callers using
            // try/catch on CatalogInputException don't get caught off guard.
            throw new CatalogInputException(
                "Malformed JSON manifest from " + source.name() + ": " + ex.getMessage(), ex);
        }
    }

    // ---------- catalog / schema / leaf parsers ----------

    private CatalogModel parseCatalog(Map<Object, Object> obj) throws CatalogInputException {
        CatalogModel.Builder b = CatalogModel.builder().name(asString(obj, "name", true));
        for (Object sobj : asList(obj, "schemas")) {
            b.addSchema(parseSchema(asMapStrict(sobj, "catalog.schemas[i]")));
        }
        return b.build();
    }

    private SchemaModel parseSchema(Map<Object, Object> obj) throws CatalogInputException {
        // Allow "" — schema-less dialects (MySQL etc.) — but require the field to be present.
        String schemaName = asString(obj, "name", true);
        SchemaModel.Builder b = SchemaModel.builder().name(schemaName);
        for (Object t : asList(obj, "tables")) {
            b.addTable(parseTable(asMapStrict(t, "schema.tables[i]")));
        }
        for (Object v : asList(obj, "views")) {
            b.addView(parseView(asMapStrict(v, "schema.views[i]")));
        }
        for (Object r : asList(obj, "routines")) {
            b.addRoutine(parseRoutine(asMapStrict(r, "schema.routines[i]")));
        }
        for (Object sy : asList(obj, "synonyms")) {
            b.addSynonym(parseSynonym(asMapStrict(sy, "schema.synonyms[i]")));
        }
        for (Object sq : asList(obj, "sequences")) {
            b.addSequence(parseSequence(asMapStrict(sq, "schema.sequences[i]")));
        }
        return b.build();
    }

    private TableModel parseTable(Map<Object, Object> obj) throws CatalogInputException {
        TableModel.Builder tb = TableModel.builder().name(asString(obj, "name", true));
        for (Object c : asList(obj, "columns")) {
            tb.addColumn(parseColumn(asMapStrict(c, "table.columns[i]")));
        }
        for (Object cs : asList(obj, "constraints")) {
            tb.addConstraint(parseConstraint(asMapStrict(cs, "table.constraints[i]")));
        }
        for (Object ix : asList(obj, "indexes")) {
            tb.addIndex(parseIndex(asMapStrict(ix, "table.indexes[i]")));
        }
        Map<Object, Object> props = asMap(obj, "properties");
        if (props != null) {
            for (Map.Entry<Object, Object> e : props.entrySet()) {
                tb.property(stringify(e.getKey()), e.getValue());
            }
        }
        return tb.build();
    }

    private ViewModel parseView(Map<Object, Object> obj) throws CatalogInputException {
        ViewModel.Builder vb = ViewModel.builder().name(asString(obj, "name", true));
        String def = asString(obj, "definition", false);
        if (def != null) vb.definition(def);
        Boolean mat = asBoolean(obj, "materialized");
        if (mat != null && mat) vb.materialized(true);
        for (Object c : asList(obj, "columns")) {
            vb.addColumn(parseColumn(asMapStrict(c, "view.columns[i]")));
        }
        return vb.build();
    }

    private ColumnModel parseColumn(Map<Object, Object> obj) throws CatalogInputException {
        ColumnModel.Builder cb = ColumnModel.builder().name(asString(obj, "name", true));
        String dt = asString(obj, "dataType", false);
        if (dt == null) dt = asString(obj, "type", false);  // tolerate "type" alias
        if (dt != null) cb.dataType(dt);
        Boolean nullable = asBoolean(obj, "nullable");
        if (nullable != null) cb.nullable(nullable);
        for (Object t : asList(obj, "policyTags")) {
            cb.addPolicyTag(parsePolicyTag(t));
        }
        for (Object t : asList(obj, "tags")) {
            // "tags" is a shorthand for plain string policy tags.
            cb.addPolicyTag(parsePolicyTag(t));
        }
        return cb.build();
    }

    private PolicyTagModel parsePolicyTag(Object obj) throws CatalogInputException {
        if (obj instanceof String) {
            return PolicyTagModel.builder().name((String) obj).build();
        }
        if (obj instanceof Map) {
            @SuppressWarnings("unchecked")
            Map<Object, Object> m = (Map<Object, Object>) obj;
            PolicyTagModel.Builder pb = PolicyTagModel.builder().name(asString(m, "name", true));
            String namespace = asString(m, "namespace", false);
            if (namespace != null) pb.namespace(namespace);
            return pb.build();
        }
        throw new CatalogInputException("policyTag entry must be a string or object");
    }

    private ConstraintModel parseConstraint(Map<Object, Object> obj) throws CatalogInputException {
        ConstraintModel.Builder cb = ConstraintModel.builder()
            .type(asString(obj, "type", true));
        String name = asString(obj, "name", false);
        if (name != null) cb.name(name);
        for (Object c : asList(obj, "columns")) {
            cb.addColumn(stringify(c));
        }
        // FK target side (optional; validator enforces FK-specific semantics).
        String referencedTable = asString(obj, "referencedTable", false);
        if (referencedTable != null) cb.referencedTable(referencedTable);
        for (Object c : asList(obj, "referencedColumns")) {
            cb.addReferencedColumn(stringify(c));
        }
        return cb.build();
    }

    private IndexModel parseIndex(Map<Object, Object> obj) throws CatalogInputException {
        String name = asString(obj, "name", true);
        IndexModel.Builder ib = IndexModel.builder().name(name);
        Boolean unique = asBoolean(obj, "unique");
        if (unique != null && unique) ib.unique(true);
        for (Object c : asList(obj, "columns")) {
            ib.addColumn(stringify(c));
        }
        try {
            return ib.build();
        } catch (IllegalArgumentException ex) {
            // IndexModel rejects empty columns lists; surface that through the
            // reader's checked-exception channel so callers can branch on it.
            throw new CatalogInputException(
                "table.indexes[" + name + "]: " + ex.getMessage(), ex);
        }
    }

    private RoutineModel parseRoutine(Map<Object, Object> obj) throws CatalogInputException {
        RoutineModel.Builder rb = RoutineModel.builder().name(asString(obj, "name", true));
        String kindStr = asString(obj, "kind", true);
        rb.kind(parseRoutineKind(kindStr));
        String returns = asString(obj, "returns", false);
        if (returns != null) rb.returns(returns);
        for (Object p : asList(obj, "parameters")) {
            rb.addParameter(parseColumn(asMapStrict(p, "routine.parameters[i]")));
        }
        return rb.build();
    }

    private SynonymModel parseSynonym(Map<Object, Object> obj) throws CatalogInputException {
        return SynonymModel.builder()
            .name(asString(obj, "name", true))
            .targetQualifiedName(asString(obj, "target", true))
            .build();
    }

    private SequenceModel parseSequence(Map<Object, Object> obj) throws CatalogInputException {
        SequenceModel.Builder sb = SequenceModel.builder().name(asString(obj, "name", true));
        Long startsWith = asLong(obj, "startsWith");
        if (startsWith != null) sb.startsWith(startsWith);
        Long incrementBy = asLong(obj, "incrementBy");
        if (incrementBy != null) sb.incrementBy(incrementBy);
        return sb.build();
    }

    private IdentifierConfig parseIdentifier(Map<Object, Object> obj, EDbVendor vendor)
            throws CatalogInputException {
        if (obj == null) return null;
        // Start from the vendor default so a manifest that overrides only one field
        // (e.g. {"preserveQuotedCase": false}) doesn't accidentally drop the vendor's
        // fold rules. Each present field replaces the default for that single key;
        // absent fields stay at their vendor default.
        IdentifierConfig defaults = IdentifierConfig.defaultsFor(vendor);
        IdentifierConfig.Builder ib = IdentifierConfig.builder().vendor(vendor)
            .foldUnquotedToUpper(defaults.foldUnquotedToUpper())
            .foldUnquotedToLower(defaults.foldUnquotedToLower())
            .preserveQuotedCase(defaults.preserveQuotedCase())
            .stripQuotedDelimiters(defaults.stripQuotedDelimiters())
            .tableCaseSensitive(defaults.tableCaseSensitive())
            .columnCaseSensitive(defaults.columnCaseSensitive())
            .mysqlLowerCaseTableNames(defaults.mysqlLowerCaseTableNames())
            .mssqlCollation(defaults.mssqlCollation());
        Boolean foldUpper = asBoolean(obj, "foldUnquotedToUpper");
        if (foldUpper != null) {
            ib.foldUnquotedToUpper(foldUpper);
            // The Builder rejects setting both fold flags to true, so reset the opposite.
            if (foldUpper) ib.foldUnquotedToLower(false);
        }
        Boolean foldLower = asBoolean(obj, "foldUnquotedToLower");
        if (foldLower != null) {
            ib.foldUnquotedToLower(foldLower);
            if (foldLower) ib.foldUnquotedToUpper(false);
        }
        Boolean preserveQuoted = asBoolean(obj, "preserveQuotedCase");
        if (preserveQuoted != null) ib.preserveQuotedCase(preserveQuoted);
        Boolean stripDelim = asBoolean(obj, "stripQuotedDelimiters");
        if (stripDelim != null) ib.stripQuotedDelimiters(stripDelim);
        Boolean tableCaseSensitive = asBoolean(obj, "tableCaseSensitive");
        if (tableCaseSensitive != null) ib.tableCaseSensitive(tableCaseSensitive);
        Boolean columnCaseSensitive = asBoolean(obj, "columnCaseSensitive");
        if (columnCaseSensitive != null) ib.columnCaseSensitive(columnCaseSensitive);
        Long lctn = asLong(obj, "mysqlLowerCaseTableNames");
        if (lctn != null) ib.mysqlLowerCaseTableNames(lctn.intValue());
        String collation = asString(obj, "mssqlCollation", false);
        if (collation != null) ib.mssqlCollation(collation);
        return ib.build();
    }

    private DefaultsConfig parseDefaults(Map<Object, Object> obj) throws CatalogInputException {
        if (obj == null) return null;
        DefaultsConfig.Builder db = DefaultsConfig.builder();
        String c = asString(obj, "catalog", false);
        if (c != null) db.defaultCatalog(c);
        String s = asString(obj, "schema", false);
        if (s != null) db.defaultSchema(s);
        String srv = asString(obj, "server", false);
        if (srv != null) db.defaultServer(srv);
        return db.build();
    }

    private CatalogSourceInfo parseSourceInfo(Map<Object, Object> obj,
                                              CatalogInputSource source,
                                              long startMillis) throws CatalogInputException {
        CatalogSourceInfo.Builder sb = CatalogSourceInfo.builder()
            .kind(source.declaredKind() != null ? source.declaredKind() : CatalogInputKind.JSON_MANIFEST);
        Long readMillis = null;
        if (obj != null) {
            String name = asString(obj, "name", false);
            if (name != null) sb.name(name);
            readMillis = asLong(obj, "readMillis");
        } else {
            sb.name(source.name() != null ? source.name() : "<json>");
        }
        // Track wall-clock parse duration when manifest didn't carry one.
        sb.readMillis(readMillis != null ? readMillis : (System.currentTimeMillis() - startMillis));
        return sb.build();
    }

    // ---------- input → string ----------

    private String readAll(CatalogInputSource source) throws CatalogInputException {
        try {
            if (source.inMemoryModel() != null) {
                throw new CatalogInputException(
                    "JsonManifestCatalogInputReader cannot read in-memory model sources");
            }
            if (source.path() != null) {
                byte[] b = Files.readAllBytes(source.path());
                return new String(b, StandardCharsets.UTF_8);
            }
            byte[] sourceBytes = source.bytes();   // defensive copy from the source
            if (sourceBytes != null) {
                return new String(sourceBytes, StandardCharsets.UTF_8);
            }
            if (source.url() != null) {
                try (InputStream in = source.url().openStream();
                     Reader r = new InputStreamReader(in, StandardCharsets.UTF_8)) {
                    return drain(r);
                }
            }
            if (source.reader() != null) {
                return drain(source.reader());
            }
            throw new CatalogInputException(
                "JsonManifestCatalogInputReader: source has no readable backing");
        } catch (IOException io) {
            throw new CatalogInputException(
                "Failed to read JSON manifest from " + source.name() + ": " + io.getMessage(), io);
        }
    }

    private static String drain(Reader r) throws IOException {
        BufferedReader br = (r instanceof BufferedReader) ? (BufferedReader) r : new BufferedReader(r);
        StringBuilder sb = new StringBuilder();
        char[] buf = new char[4096];
        int n;
        while ((n = br.read(buf)) > 0) {
            sb.append(buf, 0, n);
        }
        return sb.toString();
    }

    // ---------- shared field accessors ----------

    private static String asString(Map<Object, Object> obj, String key, boolean required)
            throws CatalogInputException {
        Object v = obj.get(key);
        if (v == null) {
            if (required) {
                throw new CatalogInputException(
                    "JSON manifest missing required field '" + key + "'");
            }
            return null;
        }
        return v instanceof String ? (String) v : v.toString();
    }

    private static Boolean asBoolean(Map<Object, Object> obj, String key) {
        Object v = obj.get(key);
        if (v == null) return null;
        if (v instanceof Boolean) return (Boolean) v;
        // Tolerate string forms emitted by some JSON encoders.
        String s = v.toString();
        if ("true".equals(s)) return Boolean.TRUE;
        if ("false".equals(s)) return Boolean.FALSE;
        return null;
    }

    private static Long asLong(Map<Object, Object> obj, String key) {
        Object v = obj.get(key);
        if (v == null) return null;
        if (v instanceof Number) return ((Number) v).longValue();
        try {
            return Long.parseLong(v.toString());
        } catch (NumberFormatException nfe) {
            return null;
        }
    }

    @SuppressWarnings("unchecked")
    private static Map<Object, Object> asMap(Map<Object, Object> obj, String key) {
        Object v = obj.get(key);
        return v instanceof Map ? (Map<Object, Object>) v : null;
    }

    @SuppressWarnings("unchecked")
    private static Map<Object, Object> asMapStrict(Object o, String location)
            throws CatalogInputException {
        if (!(o instanceof Map)) {
            throw new CatalogInputException(location + " must be a JSON object (got "
                + typeOf(o) + ")");
        }
        return (Map<Object, Object>) o;
    }

    /**
     * Accessor for an array-typed field. A missing field returns the empty list, but a
     * present non-list value is malformed and surfaces as {@link CatalogInputException}
     * — silently dropping it would leave the caller's snapshot incomplete with no signal.
     */
    @SuppressWarnings("unchecked")
    private static List<Object> asList(Map<Object, Object> obj, String key)
            throws CatalogInputException {
        Object v = obj.get(key);
        if (v == null) return Collections.emptyList();
        if (v instanceof List) return (List<Object>) v;
        throw new CatalogInputException(
            "JSON manifest field '" + key + "' must be an array (got " + typeOf(v) + ")");
    }

    private static String stringify(Object o) {
        return o == null ? null : (o instanceof String ? (String) o : o.toString());
    }

    private static String typeOf(Object o) {
        return o == null ? "null" : o.getClass().getSimpleName();
    }

    private static EDbVendor parseVendor(String raw) throws CatalogInputException {
        if (raw == null || raw.isEmpty()) {
            throw new CatalogInputException("JSON manifest 'vendor' is required");
        }
        // Try direct enum match first (e.g. "dbvoracle").
        for (EDbVendor v : EDbVendor.values()) {
            if (v.name().equals(raw)) return v;
        }
        // Then try with the "dbv" prefix prepended (e.g. "oracle" → "dbvoracle").
        for (EDbVendor v : EDbVendor.values()) {
            if (v.name().equals("dbv" + raw)) return v;
        }
        // Hand-coded ASCII case-insensitive fallback so users can write "Oracle" or "ORACLE".
        for (EDbVendor v : EDbVendor.values()) {
            String n = v.name();
            if (asciiEqualsIgnoreCase(n, raw) || asciiEqualsIgnoreCase(n, "dbv" + raw)) {
                return v;
            }
        }
        throw new CatalogInputException(
            "Unknown vendor '" + raw + "'; expected an EDbVendor name (e.g. 'oracle' or 'dbvoracle')");
    }

    /**
     * Parse a routine.kind string into the appropriate {@link CatalogObjectKind}. Only
     * the four routine-kind values are accepted — TABLE / VIEW / SCHEMA etc. are
     * structurally invalid here and surface through the reader's
     * {@link CatalogInputException} channel rather than letting the model builder throw
     * an unchecked {@link IllegalArgumentException} downstream.
     */
    private static CatalogObjectKind parseRoutineKind(String raw) throws CatalogInputException {
        if (raw == null) {
            throw new CatalogInputException("routine.kind is required");
        }
        for (CatalogObjectKind k : ROUTINE_KINDS) {
            if (k.name().equals(raw)) return k;
        }
        // ASCII case-insensitive fallback (forbidden-apis bans equalsIgnoreCase).
        for (CatalogObjectKind k : ROUTINE_KINDS) {
            if (asciiEqualsIgnoreCase(k.name(), raw)) return k;
        }
        throw new CatalogInputException(
            "Unknown routine kind '" + raw + "'; expected FUNCTION / PROCEDURE / PACKAGE / ROUTINE");
    }

    private static final CatalogObjectKind[] ROUTINE_KINDS = new CatalogObjectKind[]{
        CatalogObjectKind.FUNCTION,
        CatalogObjectKind.PROCEDURE,
        CatalogObjectKind.PACKAGE,
        CatalogObjectKind.ROUTINE,
    };

    /**
     * ASCII-only case-insensitive compare. The forbidden-apis Maven plugin (plan §9.5)
     * bans {@link String#equalsIgnoreCase(String)} inside {@code catalog/**} because
     * it's normally a flag for misuse on identifier folding. JSON keyword parsing
     * genuinely benefits from a relaxed match (manifests are written by humans), so we
     * hand-code the comparison instead of routing through {@code IdentifierService}
     * (which would be misleading: this is enum-tag matching, not identifier semantics).
     */
    private static boolean asciiEqualsIgnoreCase(String a, String b) {
        if (a == null || b == null) return a == b;
        int len = a.length();
        if (b.length() != len) return false;
        for (int i = 0; i < len; i++) {
            char ca = a.charAt(i);
            char cb = b.charAt(i);
            if (ca == cb) continue;
            char la = (ca >= 'A' && ca <= 'Z') ? (char) (ca + 32) : ca;
            char lb = (cb >= 'A' && cb <= 'Z') ? (char) (cb + 32) : cb;
            if (la != lb) return false;
        }
        return true;
    }

    private static boolean endsWithIgnoreAscii(String s, String suffix) {
        if (s.length() < suffix.length()) return false;
        return asciiEqualsIgnoreCase(s.substring(s.length() - suffix.length()), suffix);
    }

    /** ServiceLoader-discoverable factory. */
    public static final class Factory implements CatalogInputReaderFactory {

        public Factory() {
            // Required no-arg constructor for ServiceLoader.
        }

        @Override
        public CatalogInputKind kind() {
            return CatalogInputKind.JSON_MANIFEST;
        }

        @Override
        public CatalogInputReader create() {
            return new JsonManifestCatalogInputReader();
        }
    }
}