core-check.js

const assert = require("node:assert/strict");
const grammar = require("../syntaxes/pgx.tmLanguage.json");
const {
  TraversalSyntaxError,
  buildTraversalStructure,
  canonicalizeTraversalBatch,
  canonicalizeTraversalSelection,
  createCompilation,
  layoutTraversalStructure,
  parseTraversal,
  projectTraversal,
  serializePointer
} = require("../pgx-core");

const nodeGrammar = grammar.patterns.find((pattern) => pattern.name === "meta.node.pgx");
assert.equal(nodeGrammar.beginCaptures[9].name, "entity.name.type.title.pgx");
assert.equal(nodeGrammar.contentName, "string.unquoted.description.pgx");
assert.equal(nodeGrammar.patterns[0].include, "#traversal");
assert.ok(grammar.repository.traversal);
const nodeGrammarMatch = new RegExp(nodeGrammar.begin).exec(
  "pgx: || A40 || traversal expression 1 || [(A28):(A29):(A30)] || data ||"
);
assert.equal(nodeGrammarMatch[5], "A40");
assert.equal(nodeGrammarMatch[9], "traversal expression 1");

const canonicalCases = new Map([
  ["A1 A2 A3", "[(A1):(A2):(A3)]"],
  ["A4:A5:A6", "[(A4):(A5):(A6)]"],
  ["(A7) (A8) (A9)", "[(A7):(A8):(A9)]"],
  ["A10 (A11 A12)", "[(A10):((A11):(A12))]"],
  ["(A13 A14) A15", "[((A13):(A14)):(A15)]"],
  ["A16 ((A17 A18) A19)", "[(A16):(((A17):(A18)):(A19))]"],
  ["((A20):(A21)) A22", "[((A20):(A21)):(A22)]"],
  ["A23 (A24 (A25 A26)) A27", "[(A23):((A24):((A25):(A26))):(A27)]"],
  ["[A28 A29 A30]", "[(A28):(A29):(A30)]"],
  ["a31 (A32:a33) A34", "[(a31):((A32):(a33)):(A34)]"],
  ["B1 D2 PRN001", "[(B1):(D2):(PRN001)]"],
  [
    '"node with spaces" "x:y" node-alpha',
    '[("node with spaces"):("x:y"):(node-alpha)]'
  ]
]);
for (const [source, expected] of canonicalCases) {
  assert.equal(canonicalizeTraversalSelection(source), expected, source);
}

const invalidCases = [
  "",
  "A28 (A29 A30",
  "A28 A29)",
  "A28::A29",
  ":A28",
  "A28:",
  "A28 ()",
  "A28 [A29]",
  "[A28] A29",
  'A28 "unterminated',
  "A28 \\broken"
];
for (const source of invalidCases) {
  assert.throws(() => canonicalizeTraversalSelection(source), TraversalSyntaxError);
}

const batchSource = [
  "# preserved instruction",
  "A1 A2 A3",
  "A4:A5:A6",
  "",
  "  A10 (A11 A12)"
].join("\r\n");
const batchExpected = [
  "# preserved instruction",
  "[(A1):(A2):(A3)]",
  "[(A4):(A5):(A6)]",
  "",
  "  [(A10):((A11):(A12))]"
].join("\r\n");
assert.equal(canonicalizeTraversalBatch(batchSource), batchExpected);
assert.throws(
  () => canonicalizeTraversalBatch("A1 A2\nA3 (A4"),
  (error) => error instanceof TraversalSyntaxError && error.message.startsWith("Line 2:")
);
assert.equal(serializePointer("B30"), "B30");
assert.equal(serializePointer("node with spaces"), '"node with spaces"');
assert.equal(serializePointer("x:y"), '"x:y"');
const escapedPointer = 'quote " and slash \\';
const escapedTraversal = parseTraversal(`[(${serializePointer(escapedPointer)})]`);
assert.equal(escapedTraversal.items[0].id, escapedPointer);
assert.equal(canonicalizeTraversalSelection("A28 nonsense"), "[(A28):(nonsense)]");
assert.throws(
  () => canonicalizeTraversalSelection("A28 nonsense", {
    validatePointer: (pointer) => pointer === "A28"
  }),
  (error) => error instanceof TraversalSyntaxError && error.message.includes("nonsense")
);

const source = [
  "pgx: || A1 || self || leaf ||",
  "pgx: || A2 || as || leaf ||",
  "pgx: || A3 || affordance || leaf ||",
  "pgx: || A4 || as-affordance || [(A2):(A3)] ||",
  "pgx: || A5 || root || [(A1):(A4)] ||"
].join("\n");
const profile = {
  schemaProfile: 1,
  nodes: [
    { sigil: "pgx", pointer: "A6", title: "profile-only", description: "leaf" }
  ]
};
const compilation = createCompilation({ source, sourceId: "fixture.pgx", profile });
assert.equal(compilation.document.nodes.length, 5);
assert.equal(compilation.profile.nodes.length, 1);
assert.equal(compilation.diagnostics.length, 0);
assert.equal(compilation.resolve("A1", { line: 4 }).provenance, "document");
assert.equal(compilation.resolve("A6", { line: 4 }).provenance, "profile");

const mixedSource = [
  "pgx: || B1 || person || leaf ||",
  "pgx: || D2 || as || leaf ||",
  "pgx: || node with spaces || spaced identity || leaf ||",
  "pgx: || a1 || lowercase identity || leaf ||",
  "pgx: || A1 || uppercase identity || leaf ||",
  'pgx: || result.alpha || mixed traversal || [(B1):(D2):("node with spaces"):(a1):(A1)] ||'
].join("\n");
const mixedCompilation = createCompilation({ source: mixedSource, sourceId: "mixed.pgx" });
assert.equal(mixedCompilation.document.nodes.length, 6);
assert.equal(
  mixedCompilation.diagnostics.filter((entry) => entry.category === "pointer-style").length,
  3
);
assert.equal(mixedCompilation.diagnostics.filter((entry) => entry.severity === "error").length, 0);
assert.equal(mixedCompilation.resolve("B1", { line: 5 }).declaration.title, "person");
assert.equal(mixedCompilation.resolve("a1", { line: 5 }).declaration.title, "lowercase identity");
assert.equal(mixedCompilation.resolve("A1", { line: 5 }).declaration.title, "uppercase identity");
assert.equal(mixedCompilation.validateReferences({ layer: "document" }).length, 0);
assert.equal(
  projectTraversal(mixedCompilation, '[("node with spaces")]', { line: 5 }, {
    inlineDepth: 0,
    display: "title",
    unresolved: "error"
  }).text,
  "[(spaced identity)]"
);
const quotedOffset = mixedSource.indexOf('"node with spaces"') + 2;
const quotedOccurrence = mixedCompilation.pointerOccurrenceAt(quotedOffset);
assert.equal(quotedOccurrence.kind, "reference");
assert.equal(quotedOccurrence.pointer, "node with spaces");
assert.equal(
  mixedSource.slice(quotedOccurrence.span.start, quotedOccurrence.span.end),
  '"node with spaces"'
);
const declarationOffset = mixedSource.indexOf("node with spaces") + 2;
assert.equal(mixedCompilation.pointerOccurrenceAt(declarationOffset).kind, "declaration");

const pointerStyleSource = [
  "A1",
  "A01",
  "AB11",
  "ABCD9",
  "CONTEXT6",
  "AB1-2",
  "ABC1.1",
  "CRAIG49.49-2",
  "natural language pointer",
  "lowercase9",
  "ESCAPE:1",
  "THISPOINTERISMUCHLONGERTHANITNEEDSTOBE999"
].map((pointer) => `pgx: || ${pointer} || title || leaf ||`).join("\n");
const pointerStyleCompilation = createCompilation({
  source: pointerStyleSource,
  sourceId: "pointer-style.pgx"
});
const pointerStyleDiagnostics = pointerStyleCompilation.diagnostics.filter(
  (entry) => entry.category === "pointer-style"
);
assert.equal(pointerStyleDiagnostics.filter((entry) => entry.severity === "hint").length, 3);
assert.equal(pointerStyleDiagnostics.filter((entry) => entry.severity === "warning").length, 4);
assert.equal(pointerStyleDiagnostics.filter((entry) => entry.severity === "error").length, 0);
assert.ok(pointerStyleCompilation.resolve("natural language pointer", { line: 8 }));
assert.ok(pointerStyleCompilation.resolve("ESCAPE:1", { line: 10 }));

const traversal = parseTraversal("[(A1):((A2):(A3))]");
assert.equal(traversal.items[0].span.start, 2);
assert.equal(traversal.items[0].wrapperSpan.start, 1);
assert.equal(traversal.items[1].kind, "group");
assert.deepEqual(traversal.items[1].items.map((item) => item.id), ["A2", "A3"]);

const structure = buildTraversalStructure(
  compilation,
  "[((A1):(A4)):(A999)]",
  { line: 4 },
  { baseOffset: 100 }
);
assert.equal(structure.pointerCount, 3);
assert.equal(structure.groupCount, 1);
assert.equal(structure.depth, 1);
assert.deepEqual(structure.children[0].path, [0]);
assert.deepEqual(structure.children[0].children.map((item) => item.path), [[0, 0], [0, 1]]);
assert.equal(structure.children[0].children[1].title, "as-affordance");
assert.equal(structure.children[0].children[1].provenance, "document");
assert.equal(structure.children[1].resolved, false);
assert.equal(structure.children[0].children[0].span.start, 103);

const geometry = layoutTraversalStructure(structure);
assert.equal(geometry.nodes.length, 5);
assert.equal(geometry.edges.length, 4);
assert.equal(geometry.nodes.find((node) => node.id === "0").kind, "group");
assert.ok(geometry.nodes.find((node) => node.id === "0.0").x < geometry.nodes.find((node) => node.id === "0.1").x);
assert.equal(geometry.nodes.find((node) => node.id === "root").x, 347.5);

const graph = compilation.graphView({ layer: "document" });
assert.equal(graph.nodes.length, 5);
assert.equal(graph.edges.length, 4);
const rootEdges = graph.edges.filter(
  (edge) => compilation.document.nodes.find((node) => node.identity === edge.from)?.pointer === "A5"
);
assert.deepEqual(rootEdges.map((edge) => edge.path), [[0], [1]]);

const direct = projectTraversal(compilation, "[(A5)]", { line: 4 }, {
  inlineDepth: 0,
  display: "title",
  unresolved: "error"
});
assert.equal(direct.ok, true);
assert.equal(direct.text, "[(root)]");
assert.equal(direct.ast.items[0].pointer, "A5");
assert.equal(direct.ast.items[0].declarationIdentity, compilation.document.nodes[4].identity);

const depthOne = projectTraversal(compilation, "[(A5)]", { line: 4 }, {
  inlineDepth: 1,
  display: "title"
});
assert.equal(depthOne.text, "[((self):(as-affordance))]");

const full = projectTraversal(compilation, "[(A5)]", { line: 4 }, {
  inlineDepth: Infinity,
  display: "title"
});
assert.equal(full.text, "[((self):((as):(affordance)))]");
assert.equal(full.stats.expandedNodes, 2);

const directTitles = projectTraversal(compilation, "[(A1):(A4)]", { line: 4 }, {
  inlineDepth: 0,
  display: "title"
});
assert.equal(directTitles.text, "[(self):(as-affordance)]");

const duplicateSource = [
  "pgx: || A1 || early || leaf ||",
  "",
  "",
  "pgx: || A1 || late || leaf ||"
].join("\n");
const duplicateCompilation = createCompilation({ source: duplicateSource });
assert.equal(duplicateCompilation.resolve("A1", { line: 0 }).declaration.title, "early");
assert.equal(duplicateCompilation.resolve("A1", { line: 3 }).declaration.title, "late");
assert.ok(duplicateCompilation.diagnostics.some((entry) => entry.code === "duplicate-document-pointer"));

const invalidCompilation = createCompilation({
  source: [
    "  pgx: || A1 || displaced || leaf ||",
    "pgx: || || missing pointer || leaf ||",
    "pgx: || A2 || malformed traversal || [(A1) ||"
  ].join("\n")
});
assert.ok(invalidCompilation.diagnostics.some((entry) => entry.category === "lawful-syntax"));
assert.ok(invalidCompilation.diagnostics.some((entry) => entry.category === "schema-profile-1"));
assert.ok(invalidCompilation.diagnostics.some((entry) => entry.code === "invalid-description-traversal"));

const cycleCompilation = createCompilation({
  source: [
    "pgx: || A7 || seven || [(A8)] ||",
    "pgx: || A8 || eight || [(A7)] ||"
  ].join("\n")
});
assert.ok(cycleCompilation.findCycles({ layer: "document" }).length > 0);
const cyclic = projectTraversal(cycleCompilation, "[(A7)]", { line: 0 }, {
  inlineDepth: Infinity,
  cycle: "marker"
});
assert.match(cyclic.text, /<cycle:A7>/);
assert.ok(cyclic.diagnostics.some((entry) => entry.code === "expansion-cycle"));

const unresolved = projectTraversal(compilation, "[(A999)]", { line: 0 }, {
  inlineDepth: Infinity,
  unresolved: "error"
});
assert.equal(unresolved.ok, false);
assert.ok(unresolved.diagnostics.some((entry) => entry.code === "unresolved-pointer"));

const depthLimited = projectTraversal(compilation, "[(A5)]", { line: 4 }, {
  inlineDepth: Infinity,
  maxDepth: 1
});
assert.equal(depthLimited.status, "truncated");
assert.ok(depthLimited.diagnostics.some((entry) => entry.code === "max-depth"));

const outputLimited = projectTraversal(compilation, "[(A5)]", { line: 4 }, {
  inlineDepth: Infinity,
  maxOutputCharacters: 10
});
assert.equal(outputLimited.status, "truncated");
assert.ok(outputLimited.diagnostics.some((entry) => entry.code === "max-output-characters"));

console.log(
  `PGX core checks passed: ${canonicalCases.size} canonicalizations, 1 batch, compilation, graph binding, projections, provenance, cycles, and budgets.`
);