Update documentation and enhance chain inspection logic
Node.js build / build (20.x) (push) Waiting to run
Node.js build / build (22.x) (push) Waiting to run

- Revamped the README to provide comprehensive documentation for the Mindnet Causal Assistant plugin, including user, administrator, developer, and architect guides.
- Added specialized documentation sections for installation, deployment, and troubleshooting.
- Enhanced the chain inspection logic to determine effective required links based on template definitions, profiles, and defaults, improving the accuracy of findings related to link completeness.
This commit is contained in:
Lars committed 2026-01-20 11:34:58 +01:00
1 parent 86c88bc275
commit 74cacdd41d
12 files changed
+5381 -41

No files matched your search

+12 -1
View File
@@ -1063,6 +1063,15 @@ export async function inspectChains(
// Add template-based findings with profile thresholds
for (const match of templateMatches) {
// Find the template definition to check for template-level required_links override
const templateDef = chainTemplates?.templates?.find(t => t.name === match.templateName);
// Determine effective required_links: template.matching > profile > defaults.matching > false
const effectiveRequiredLinks = templateDef?.matching?.required_links ??
profile?.required_links ??
chainTemplates?.defaults?.matching?.required_links ??
false;
// missing_slot_<slotId> findings (with profile thresholds)
if (match.missingSlots.length > 0) {
const slotsFilled = Object.keys(match.slotAssignments).length;
@@ -1086,7 +1095,9 @@ export async function inspectChains(
}
// missing_link_constraints finding
if (match.slotsComplete && match.requiredLinks > 0 && !match.linksComplete) {
// Only emit if required_links=true (strict mode)
// In soft mode (required_links=false), suppress this finding even if links are incomplete
if (effectiveRequiredLinks && match.slotsComplete && match.requiredLinks > 0 && !match.linksComplete) {
findings.push({
code: "missing_link_constraints",
severity: applySeverityPolicy(profileName as "discovery" | "decisioning" | undefined, "missing_link_constraints", "info"),
@@ -0,0 +1,385 @@
/**
* Tests for required_links suppression of missing_link_constraints findings.
*/
import { describe, it, expect, vi, beforeEach } from "vitest";
import type { App, TFile } from "obsidian";
import { inspectChains } from "../../analysis/chainInspector";
import type { SectionContext } from "../../analysis/sectionContext";
import type { ChainRolesConfig, ChainTemplatesConfig } from "../../dictionary/types";
import { parseEdgeVocabulary } from "../../vocab/parseEdgeVocabulary";
import { VocabularyLoader } from "../../vocab/VocabularyLoader";
// Mock VocabularyLoader
vi.mock("../../vocab/VocabularyLoader", () => ({
VocabularyLoader: {
loadText: vi.fn(),
},
}));
describe("Chain Inspector required_links suppression", () => {
let mockApp: App;
let mockFileA: TFile;
let mockFileB: TFile;
let mockFileC: TFile;
beforeEach(() => {
mockFileA = {
path: "NoteA.md",
name: "NoteA.md",
extension: "md",
basename: "NoteA",
} as TFile;
mockFileB = {
path: "NoteB.md",
name: "NoteB.md",
extension: "md",
basename: "NoteB",
} as TFile;
mockFileC = {
path: "NoteC.md",
name: "NoteC.md",
extension: "md",
basename: "NoteC",
} as TFile;
mockApp = {
vault: {
getAbstractFileByPath: vi.fn(),
read: vi.fn(),
getMarkdownFiles: vi.fn().mockReturnValue([]),
cachedRead: vi.fn(),
},
metadataCache: {
getFileCache: vi.fn().mockReturnValue(null),
getFirstLinkpathDest: vi.fn().mockReturnValue(null),
getBacklinksForFile: vi.fn().mockReturnValue(new Map()) as any,
},
} as unknown as App;
vi.mocked(VocabularyLoader.loadText).mockResolvedValue("");
});
it("should emit missing_link_constraints when required_links=true", async () => {
// Setup: Template match with slotsComplete=true, requiredLinks>0, but linksComplete=false
// We need both decision and insight nodes, and an edge between them
const contentA = `# Note A
## Decision
Some decision content.
> [!edge] causes
> [[NoteB]]
`;
const contentB = `# Note B
## Insight
Some insight content.
`;
const chainRoles: ChainRolesConfig = {
roles: {
causal: {
edge_types: ["causes"],
},
},
};
const chainTemplates: ChainTemplatesConfig = {
defaults: {
profiles: {
decisioning: {
required_links: true, // Strict mode
min_slots_filled_for_gap_findings: 1,
min_score_for_gap_findings: 0,
},
},
},
templates: [
{
name: "decision_logic",
slots: ["decision", "insight"],
links: [
{ from: "decision", to: "insight" },
],
},
],
};
vi.mocked(mockApp.vault.getAbstractFileByPath).mockImplementation(
(path: string) => {
if (path === "NoteA.md") return mockFileA;
if (path === "NoteB.md") return mockFileB;
return null;
}
);
vi.mocked(mockApp.vault.read).mockImplementation((file: TFile) => {
if (file.path === "NoteA.md") return Promise.resolve(contentA);
if (file.path === "NoteB.md") return Promise.resolve(contentB);
return Promise.resolve("");
});
const context: SectionContext = {
file: "NoteA.md",
heading: "Decision",
zoneKind: "content",
sectionIndex: 1,
};
const report = await inspectChains(
mockApp,
context,
{
includeNoteLinks: true,
includeCandidates: false,
maxDepth: 3,
direction: "both",
},
chainRoles,
undefined,
chainTemplates,
{
path: "_system/dictionary/chain_templates.yaml",
status: "loaded",
loadedAt: Date.now(),
templateCount: 1,
},
"decisioning"
);
// Should have template match (if slots can be assigned)
expect(report.templateMatches).toBeDefined();
// Find match if it exists
const match = report.templateMatches?.find(m => m.templateName === "decision_logic");
// Only verify finding if we have a match with incomplete links
if (match && match.slotsComplete && match.requiredLinks > 0 && !match.linksComplete) {
// Verify report still includes link counts (transparency)
expect(match.satisfiedLinks).toBeDefined();
expect(match.requiredLinks).toBeDefined();
// Should have missing_link_constraints finding (strict mode)
const missingLinkFinding = report.findings.find(f => f.code === "missing_link_constraints");
expect(missingLinkFinding).toBeDefined();
expect(missingLinkFinding?.message).toContain("decision_logic");
expect(missingLinkFinding?.message).toContain("link constraints missing");
}
// Verify profile config
expect(report.templateMatchingProfileUsed?.profileConfig?.required_links).toBe(true);
});
it("should NOT emit missing_link_constraints when required_links=false", async () => {
// Setup: Same template match, but with required_links=false (soft mode)
const contentA = `# Note A
## Decision
Some decision content.
> [!edge] causes
> [[NoteB]]
`;
const contentB = `# Note B
## Insight
Some insight content.
`;
const chainRoles: ChainRolesConfig = {
roles: {
causal: {
edge_types: ["causes"],
},
},
};
const chainTemplates: ChainTemplatesConfig = {
defaults: {
profiles: {
discovery: {
required_links: false, // Soft mode
min_slots_filled_for_gap_findings: 1,
min_score_for_gap_findings: 0,
},
},
},
templates: [
{
name: "decision_logic",
slots: ["decision", "insight"],
links: [
{ from: "decision", to: "insight" },
],
},
],
};
vi.mocked(mockApp.vault.getAbstractFileByPath).mockImplementation(
(path: string) => {
if (path === "NoteA.md") return mockFileA;
if (path === "NoteB.md") return mockFileB;
return null;
}
);
vi.mocked(mockApp.vault.read).mockImplementation((file: TFile) => {
if (file.path === "NoteA.md") return Promise.resolve(contentA);
if (file.path === "NoteB.md") return Promise.resolve(contentB);
return Promise.resolve("");
});
const context: SectionContext = {
file: "NoteA.md",
heading: "Decision",
zoneKind: "content",
sectionIndex: 1,
};
const report = await inspectChains(
mockApp,
context,
{
includeNoteLinks: true,
includeCandidates: false,
maxDepth: 3,
direction: "both",
},
null,
undefined,
chainTemplates,
{
path: "_system/dictionary/chain_templates.yaml",
status: "loaded",
loadedAt: Date.now(),
templateCount: 1,
},
"discovery"
);
// Should have template match (if slots can be assigned)
expect(report.templateMatches).toBeDefined();
// Find match if it exists
const match = report.templateMatches?.find(m => m.templateName === "decision_logic");
// Only verify finding suppression if we have a match with incomplete links
if (match && match.slotsComplete && match.requiredLinks > 0 && !match.linksComplete) {
// Verify report still includes link counts (transparency maintained)
expect(match.satisfiedLinks).toBeDefined();
expect(match.requiredLinks).toBeDefined();
// Should NOT have missing_link_constraints finding (soft mode suppresses it)
const missingLinkFinding = report.findings.find(f => f.code === "missing_link_constraints");
expect(missingLinkFinding).toBeUndefined();
}
// Verify profile config
expect(report.templateMatchingProfileUsed?.profileConfig?.required_links).toBe(false);
});
it("should respect template-level required_links override", async () => {
// Setup: Profile has required_links=false, but template overrides to true
const contentA = `# Note A
## Decision
Some decision content.
> [!edge] causes
> [[NoteB]]
`;
const contentB = `# Note B
## Insight
Some insight content.
`;
const chainRoles: ChainRolesConfig = {
roles: {
causal: {
edge_types: ["causes"],
},
},
};
const chainTemplates: ChainTemplatesConfig = {
defaults: {
profiles: {
discovery: {
required_links: false, // Profile says soft mode
min_slots_filled_for_gap_findings: 1,
min_score_for_gap_findings: 0,
},
},
},
templates: [
{
name: "decision_logic",
slots: ["decision", "insight"],
links: [
{ from: "decision", to: "insight" },
],
matching: {
required_links: true, // Template overrides to strict mode
},
},
],
};
vi.mocked(mockApp.vault.getAbstractFileByPath).mockImplementation(
(path: string) => {
if (path === "NoteA.md") return mockFileA;
if (path === "NoteB.md") return mockFileB;
return null;
}
);
vi.mocked(mockApp.vault.read).mockImplementation((file: TFile) => {
if (file.path === "NoteA.md") return Promise.resolve(contentA);
if (file.path === "NoteB.md") return Promise.resolve(contentB);
return Promise.resolve("");
});
const context: SectionContext = {
file: "NoteA.md",
heading: "Decision",
zoneKind: "content",
sectionIndex: 1,
};
const report = await inspectChains(
mockApp,
context,
{
includeNoteLinks: true,
includeCandidates: false,
maxDepth: 3,
direction: "both",
},
null,
undefined,
chainTemplates,
{
path: "_system/dictionary/chain_templates.yaml",
status: "loaded",
loadedAt: Date.now(),
templateCount: 1,
},
"discovery"
);
// Should have template match
expect(report.templateMatches).toBeDefined();
const match = report.templateMatches?.find(m => m.templateName === "decision_logic");
expect(match).toBeDefined();
if (match && match.slotsComplete && match.requiredLinks > 0 && !match.linksComplete) {
// Template-level override should make this strict, so finding should appear
const missingLinkFinding = report.findings.find(f => f.code === "missing_link_constraints");
expect(missingLinkFinding).toBeDefined();
}
});
});