@@ -89,9 +89,9 @@ private ArtifactDiscovery() {}
             new Rule("*.json", "json", List.of("unknown")),
             new Rule("*.xml", "xml", List.of("unknown")));
 
-    // Adapted from python's (which is pip-shaped) to Java's build output. `build` and `target` are
-    // the same class of exclusion the L1 extractor learned in #199: Gradle's build/resources copies
-    // of test fixtures are build output, not project code, and the lesson generalises to artifacts.
+    // Scoped to Java build output. `build` and `target` are the same class of exclusion the L1
+    // extractor learned in #199: Gradle's build/resources copies of test fixtures are build output,
+    // not project code, and the lesson generalises to artifacts.
     private static final Set<String> IGNORED = Set.of(
             ".git", ".hg", ".svn", "target", "build", "out", "bin",
             ".gradle", ".mvn", ".idea", ".settings", "node_modules",
@@ -185,10 +185,9 @@ public static Map<String, JArtifact> discover(
         return artifacts;
     }
 
-    // Directory-segment check only -- deliberately NOT python's
-    // `any(part in IGNORED for part in rel.parts)`, which also matches a *file* literally named
-    // "build" or "target" because it tests every segment including the leaf. Checking only the
-    // segments strictly above the file name is the fix; do not "correct" this back to match python.
+    // Directory segments only, deliberately: testing every segment including the leaf would also
+    // match a *file* literally named "build" or "target". Only the segments strictly above the file
+    // name are checked -- do not "simplify" this into a check over all segments.
     private static boolean isIgnored(Path relative) {
         int dirSegments = relative.getNameCount() - 1;
         for (int i = 0; i < dirSegments; i++) {
@@ -219,9 +218,9 @@ private static Rule classify(String relPosix) {
         return null;
     }
 
-    // Only '*' appears anywhere in RULES, so that is all this translates. This mirrors python's
-    // fnmatch semantics (a plain regex wildcard, so '*' can cross '/') rather than java.nio's glob
-    // PathMatcher, whose '*' stops at a path separator and would silently narrow "k8s/*.yml".
+    // Only '*' appears anywhere in RULES, so that is all this translates. '*' is a plain regex
+    // wildcard here and so can cross '/', unlike java.nio's glob PathMatcher, whose '*' stops at a
+    // path separator and would silently narrow "k8s/*.yml".
     private static boolean globMatches(String pattern, String target) {
         StringBuilder regex = new StringBuilder();
         for (String literal : pattern.split("\\*", -1)) {
@@ -244,9 +243,9 @@ private static String decodeStrict(byte[] raw) {
 
     /**
      * Decode a byte prefix for a truncated capture. The cap can land mid-character; IGNORE drops
-     * the dangling partial character at the cut instead of throwing, matching python's {@code
-     * errors="ignore"}. Only called on bytes already proven fully UTF-8 decodable by {@link
-     * #decodeStrict}, so the sole possible error is that one boundary character.
+     * the dangling partial character at the cut instead of throwing. Only called on bytes already
+     * proven fully UTF-8 decodable by {@link #decodeStrict}, so the sole possible error is that one
+     * boundary character.
      */
     private static String decodeLenientPrefix(byte[] raw, int len) {
         try {
 
@@ -31,12 +31,10 @@
 /**
  * Flattens config-bearing artifacts into {@link JConfigKey} records: pure text-in/records-out,
  * same idiom as {@link ManifestParsers} -- one dispatcher over per-format internals, never
- * throwing. Mirrors codeanalyzer-python's {@code artifacts/config_keys.py}, but narrower: only
- * {@code properties}/{@code yaml}/{@code xml}/{@code dockerfile} plus env-family basenames are
- * handled here (python's {@code json}/{@code toml}/{@code ini} vocabulary has no Java-side
- * artifact format to hang off, per the plan). The {@code xml} flattener is net-new -- python has
- * none to emulate -- and is deliberately the simplest scheme that could work (see {@link
- * #walkXml}).
+ * throwing. Deliberately narrow: only {@code properties}/{@code yaml}/{@code xml}/{@code
+ * dockerfile} plus env-family basenames are handled, because no other config format has a Java-side
+ * artifact format to hang off. The {@code xml} flattener is deliberately the simplest scheme that
+ * could work (see {@link #walkXml}).
  *
  * <p>Namespace dispatch: an env-family basename ({@code .env}, {@code .env.*}) always wins,
  * regardless of the artifact's declared {@code format} (matching {@code ArtifactDiscovery}, which
@@ -63,7 +61,7 @@
  * files are line-oriented so the parse itself knows the exact line, but {@code properties} (parsed
  * via {@link Properties}, which exposes no position info) and {@code yaml}/{@code xml} (tree-shaped)
  * carry no span at all here -- an accepted gap, matching the brief ("best-effort... null is
- * acceptable"; python's own yaml/json/toml spans are already only a regex approximation).
+ * acceptable").
  */
 public final class ConfigKeys {
 
@@ -208,8 +206,8 @@ private static List<Entry> flatten(Object obj, String prefix) {
     }
 
     // Compose's `services.<name>.environment` block only (a map of KEY: value, or a list of
-    // "KEY=value"/bare "KEY" strings) -- python's k8s `env[].name`/`.value` list-shape recognition
-    // is deliberately not ported, the brief names compose only.
+    // "KEY=value"/bare "KEY" strings). Kubernetes' `env[].name`/`.value` list shape is deliberately
+    // not recognized -- the brief names compose only.
     private static final Pattern COMPOSE_ENV = Pattern.compile("^services\\.[^.]+\\.environment\\.(.+)$");
 
     private static List<Entry> recognizeComposeEnv(List<Entry> flat) {
@@ -246,7 +244,7 @@ private static boolean isDigits(String s) {
         return true;
     }
 
-    // ---- xml: net-new, python has no XML flattener to emulate. Deliberately the simplest scheme
+    // ---- xml: deliberately the simplest scheme
     // that could work -- see walkXml -- not a richer one (no XPath predicates, no namespace-aware
     // qualified-name handling). Reuses ManifestParsers' hardened DocumentBuilderFactory rather than
     // building a second one: untrusted repository content gets the same XXE hardening either way. -
@@ -310,7 +308,7 @@ private static List<Element> directChildElements(Element parent) {
     // ---- dockerfile: `ENV`/`ARG` directives. Line-based, case-insensitive instruction keywords
     // (Dockerfile convention is uppercase; the spec itself is not case-sensitive).
     //
-    // Two known gaps, carried over from python rather than rediscovered: no BuildKit heredoc
+    // Two known and accepted gaps: no BuildKit heredoc
     // awareness (a heredoc body line is just another line that doesn't match ENV/ARG and is
     // silently skipped, same as any other unparseable line); no multi-stage `FROM ... AS` scoping
     // (every ENV/ARG in the file is scanned regardless of which stage it is in). --------------
@@ -319,7 +317,7 @@ private static List<Element> directChildElements(Element parent) {
     private static final Pattern DOCKER_ARG = Pattern.compile("^ARG\\s+(.*)$", Pattern.CASE_INSENSITIVE);
 
     // Joins a possibly backslash-continued logical instruction line, starting at lines[startIdx].
-    // No separator is inserted between joined parts (matching python) -- a space survives only if
+    // No separator is inserted between joined parts -- a space survives only if
     // it was already present before the continuation backslash on the physical line.
     private static final class Joined {
         final String text;
@@ -346,8 +344,8 @@ private static Joined joinContinuations(String[] lines, int startIdx) {
      * Whitespace-split {@code s}, except inside a matching quote span (a quoted value may contain
      * spaces) or right after an unquoted {@code \} (a backslash escapes the next character). Quote
      * characters stay IN the returned tokens, stripped afterward by {@link #envValue} so there is
-     * one quote-stripping implementation, not two. Direct port of python's {@code
-     * _split_ws_respecting_quotes}, for Docker's shell-style {@code ENV} splitting.
+     * one quote-stripping implementation, not two. This is Docker's shell-style {@code ENV}
+     * splitting.
      */
     private static List<String> splitWsRespectingQuotes(String s) {
         List<String> tokens = new ArrayList<>();
@@ -514,8 +512,8 @@ private static List<Entry> parseEnvFile(String text) {
     // placeholder / Maven property, e.g. `${spring.datasource.url}`), unlike a shell env var --
     // hence the braced identifier class allows `.` where the bare one deliberately does not (a
     // shell variable name never contains a dot). No `${{ ... }}` template or `%(name)s`
-    // percent-interpolation form: those are python-reference-only vocabulary the brief does not
-    // name for Java. --------------------------------------------------------------------------
+    // percent-interpolation form: neither is Java vocabulary, and the brief does not name them.
+    // ------------------------------------------------------------------------------------------
 
     private static final Pattern REF_BRACED = Pattern.compile("\\$\\{[A-Za-z_][A-Za-z0-9_.]*\\}");
     private static final Pattern REF_BARE = Pattern.compile("\\$[A-Za-z_][A-Za-z0-9_]*");
 
@@ -18,20 +18,20 @@
 
 /**
  * Assembles the emitted {@link JDependency} list from every {@code dependency-manifest} artifact
- * {@code ArtifactDiscovery} found, then reconciles it against any lockfile. Mirrors
- * codeanalyzer-python's {@code artifacts/dependencies.py} two-step shape -- declare, then backfill
- * from the lock -- but drops its import-binding layer entirely: python needs an alias table because
- * a PyPI distribution name is not its import name, so a same-name guess is a genuine heuristic
- * worth making. A Java package is declared at the call site with no such naming mismatch, so the
- * analogous guess here would be strictly worse than emitting nothing -- {@code provides_imports}/
- * {@code unresolved_imports} are deliberately not ported.
+ * {@code ArtifactDiscovery} found, then reconciles it against any lockfile: declare first, then
+ * backfill the resolved versions from the lock.
+ *
+ * <p>No import-binding layer: a Java package is declared at the call site, so a distribution-name
+ * to import-name mapping has nothing to resolve. Emitting a same-name guess would be strictly
+ * worse than emitting nothing, so {@code provides_imports}/{@code unresolved_imports} are
+ * deliberately absent rather than guessed.
  */
 public final class DependencyView {
 
     private DependencyView() {}
 
-    // The one basename ManifestParsers.parseLockPins recognizes today. Mirrors python's
-    // _LOCK_BASENAMES tuple (three entries, one per format pip's ecosystem has); Gradle has one.
+    // The one basename ManifestParsers.parseLockPins recognizes today: Gradle has a single
+    // lockfile format, so this set has a single entry.
     private static final Set<String> LOCK_BASENAMES = Set.of("gradle.lockfile");
 
     /**
@@ -47,7 +47,7 @@ public static List<JDependency> build(Path projectDir, Map<String, JArtifact> ar
         List<JDependency> deps = new ArrayList<>();
 
         // 1. Declared: every dependency-manifest artifact that is not itself a lockfile (locks are
-        // handled by step 2 below, matching python's explicit _LOCK_BASENAMES skip here).
+        // handled by step 2 below, so they are explicitly skipped here).
         for (String path : paths) {
             if (isLockfile(path)) {
                 continue;
@@ -75,8 +75,7 @@ public static List<JDependency> build(Path projectDir, Map<String, JArtifact> ar
 
         // 2. Lock backfill: a pin matching a declared dependency (by group:name) sets its
         // lockedVersion; a pin with no declaration is itself emitted as a transitive dependency.
-        // This is python's reconciliation (dependencies.py:181-186) and knowingly contradicts the
-        // spec's "transitive out of scope" -- see .github#48.
+        // This knowingly contradicts the spec's "transitive out of scope" -- see .github#48.
         Map<String, String> pins = new HashMap<>();
         Map<String, String> pinLockArtifact = new HashMap<>();
         for (String path : paths) {
@@ -168,8 +167,8 @@ private static String basename(String path) {
      *
      * <p>Deliberately {@code public}, a narrow named exception to this class's "public surface is
      * just {@code build}" rule: the design plan requires this from-disk logic to exist exactly
-     * once, in contrast to the reference implementation, which duplicates it verbatim across two
-     * modules with a "keep the two in sync" comment. The config-key extraction pass ({@code
+     * once, rather than being duplicated across modules with a "keep the two in sync" comment.
+     * The config-key extraction pass ({@code
      * ConfigKeys}/{@code CodeAnalyzer}, package {@code com.ibm.cldk}) needs the identical read and
      * must call this rather than re-write it -- do not shrink this back to {@code private}.
      */
 
@@ -24,18 +24,17 @@
  * no mutation of anything — {@code DependencyView} (a later task in this layer) is what touches
  * disk and assembles these records into the emitted {@code JDependency} model.
  *
- * <p>This mirrors codeanalyzer-python's {@code artifacts/parsers.py} {@code (records, partial)}
- * convention: a whole-file parse failure (a malformed {@code pom.xml}) differs from a per-line one
- * (an unrecognized Gradle declaration). The former keeps the artifact but flags extraction; the
- * latter is silently skipped and the file still succeeds. The vocabulary is deliberately free-form
- * strings rather than enums, matching v1.3.0: {@code kind} is one of {@code
+ * <p>Parsers return {@code (records, partial)}: a whole-file parse failure (a malformed {@code
+ * pom.xml}) differs from a per-line one (an unrecognized Gradle declaration). The former keeps the
+ * artifact but flags extraction; the latter is silently skipped and the file still succeeds. The
+ * vocabulary is deliberately free-form strings rather than enums: {@code kind} is one of {@code
  * runtime|dev|optional|build} — four values, even though Maven has six scopes.
  */
 public final class ManifestParsers {
 
     private ManifestParsers() {}
 
-    /** A parsed declaration, before reconciliation. Mirrors python's frozen {@code RawDep}. */
+    /** A parsed declaration, before reconciliation. Immutable. */
     public static final class RawDep {
         public final String group;
         public final String name;
@@ -64,11 +63,11 @@ public static final class ParseResult {
     }
 
     // Configuration keyword, then a 'g:a:v' or "g:a:v" string literal on the same line. Deliberately
-    // shallow, exactly as python's setup.py reader is deliberately static: a build.gradle is a
+    // shallow and purely static: a build.gradle is a
     // program (variables, `ext {}` properties, version catalogs, multi-line calls), and evaluating
     // it is out of scope. An interpolated version like "$springVersion" is captured verbatim as
-    // `spec` with no resolved value -- a known gap, not a bug, matching the reference's identical
-    // setup.py gap. A line spanning a call across multiple lines, or a project(...) reference with
+    // `spec` with no resolved value -- a known gap, not a bug.
+    // A line spanning a call across multiple lines, or a project(...) reference with
     // no coordinate literal at all, simply does not match and is skipped like any other line.
     private static final Pattern GRADLE_DEP_LINE = Pattern.compile(
             "\\b(implementation|api|compileOnly|runtimeOnly|testImplementation|annotationProcessor)\\b"
 
@@ -48,9 +48,9 @@
  * ({@link CypherWriter} snapshot / {@link BoltWriter} incremental) consume the returned
  * {@link GraphRows}.
  *
- * <p>Modelling decisions (mirrors the codeanalyzer-typescript Neo4j projection; all node labels are
- * {@code J}-prefixed and relationship types {@code J_}-prefixed so a Java graph can share a Neo4j
- * database with the Python/TypeScript backends without colliding):
+ * <p>Modelling decisions (all node labels are {@code J}-prefixed and relationship types
+ * {@code J_}-prefixed so a Java graph can share a Neo4j database with a sibling language's
+ * analyzer without colliding):
  * <ul>
  *   <li>{@code JType} and {@code JCallable} carry a shared {@code :JSymbol} label (the global-identity
  *       / MERGE key); their {@code id} is the FQN (types) or {@code <fqn>#<signature>} (callables).</li>