Update documentation and enhance chain inspection logic
- 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:
1 parent
86c88bc275
commit
74cacdd41d
12 files changed
+5381
-41
No files matched your search
@@ -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();
|
||||
}
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user