package p.studio.api.automation; import java.nio.file.Path; import java.util.List; import java.util.Objects; /** Installed, owner-maintained knowledge. Authentication belongs to the calling adapter. */ public interface ProjectKnowledge { Context context(Path openProjectRoot); ReferencePage readReference(Path openProjectRoot, String referenceId, int offset, int limit); record Version(String value, String source) { public Version { Objects.requireNonNull(source, "source"); if (source.isBlank() || value != null && value.isBlank()) throw new IllegalArgumentException("Blank version provenance"); } public boolean known() { return value != null; } public static Version unknown() { return new Version(null, "unknown"); } } enum Support { SUPPORTED, UNSUPPORTED, UNKNOWN } record Capability(String name, Support support, String limitation) { public Capability { Objects.requireNonNull(name); Objects.requireNonNull(support); } } record Language(String id, boolean primary, Version languageVersion, Version compilerVersion, Version sdkVersion, List extensions, List sourceRoots, List capabilities, List referenceIds) { public Language { Objects.requireNonNull(id); Objects.requireNonNull(languageVersion); Objects.requireNonNull(compilerVersion); Objects.requireNonNull(sdkVersion); extensions = List.copyOf(extensions); sourceRoots = List.copyOf(sourceRoots); capabilities = List.copyOf(capabilities); referenceIds = List.copyOf(referenceIds); } } enum ReferenceKind { QUICKSTART, SYNTAX, SEMANTICS, EXAMPLE, SDK, LIBRARY } record Reference(String id, String title, String owner, ReferenceKind kind, Version version) { public Reference { Objects.requireNonNull(id); Objects.requireNonNull(title); Objects.requireNonNull(owner); Objects.requireNonNull(kind); Objects.requireNonNull(version); } } record Library(String id, Version version, List roots, boolean editable) { public Library { Objects.requireNonNull(id); Objects.requireNonNull(version); roots = List.copyOf(roots); } } record Context(Path projectRoot, String projectName, List languages, List libraries, List editableRoots, List readOnlyRoots, List references, List limitations) { public Context { projectRoot = Objects.requireNonNull(projectRoot).toAbsolutePath().normalize(); Objects.requireNonNull(projectName); languages = List.copyOf(languages); libraries = List.copyOf(libraries); editableRoots = List.copyOf(editableRoots); readOnlyRoots = List.copyOf(readOnlyRoots); references = List.copyOf(references); limitations = List.copyOf(limitations); } } /** Offsets and limits count Unicode code points, not bytes or UTF-16 code units. */ record ReferencePage(String referenceId, int offset, int total, Integer nextOffset, String text) { public ReferencePage { Objects.requireNonNull(referenceId); Objects.requireNonNull(text); int count = text.codePointCount(0, text.length()); if (offset < 0 || total < offset || count > total - offset || (nextOffset == null && count != total - offset) || (nextOffset != null && (nextOffset != offset + count || nextOffset >= total || count == 0))) throw new IllegalArgumentException("Invalid reference page"); } } }